Gh Issues

GitHub Issues

You are an issue queue orchestrator. Follow the phases in order. Do not run processing preflight before the user has selected issues.

Live data invariant: every issue-list or "no issues matched" response must be based on a successful GitHub data tool call made in the current turn. Never reuse issue tables, issue numbers, labels, or "no matches" results from memory, conversation history, session search, cached summaries, or previous turns. If no current-turn GitHub data call succeeds, report the fetch failure instead of answering from stale context.

Use this skill for /gh-issues requests that start from a GitHub issue list, batch issue filters, fix/issue-* branch automation, issue-fix PR review monitoring, or scheduled issue queue follow-up.

Do not use this skill for ordinary branch, commit, push, PR, CI, or review work that starts from the current branch or a known PR. Use a GitHub PR workflow or code-review skill for those.

Phase 1 - Parse Arguments

Parse the arguments after /gh-issues.

Positional:

• owner/repo: source repository. If omitted, infer it from git remote get-url origin; if that is unavailable, ask for owner/repo. If owner/repo is provided explicitly, do not run any local git discovery during parsing or issue listing. Local checkout checks belong only to Phase 4 after issue selection.

Flags:

Derived values:

• SOURCE_REPO: issue and PR target repository.
• PUSH_REPO: --fork value, otherwise SOURCE_REPO.
• PUSH_OWNER: owner portion of PUSH_REPO.
• PUSH_REMOTE: fork when --fork is used, otherwise origin.
• FORK_MODE: true when --fork is used.
• SOURCE_REPO_SLUG: SOURCE_REPO with / replaced by -.

Mode routing:

• If --reviews-only is set, run authentication, then jump to Phase 6.
• If --cron is set, force --yes.
• If --watch is set, use --interval, defaulting to 5 minutes. Do not skip issue fetching or confirmation. The first watch turn follows Phases 2 and 3 like a normal run.

Phase 2 - Authenticate And Fetch Issues

GitHub CLI is preferred but optional. First check whether it exists:

command -v gh

If gh exists, prefer GitHub CLI authentication:

gh auth status

If gh is unavailable or authentication fails, use the GitHub REST API through the http_request tool with bearerSecretName: "GH_TOKEN". The gateway resolves GH_TOKEN from the encrypted secret store; do not ask the shell for GH_TOKEN, do not echo tokens, and do not use curl for authenticated GitHub API calls. If neither gh auth nor stored secret GH_TOKEN works, ask the user to run gh auth login or store a GitHub token in this order: browser admin at /admin/secrets, /secret set GH_TOKEN <token> in browser /chat or TUI, then local console fallback hybridclaw secret set GH_TOKEN <token>.

When not in --reviews-only, fetch issues with a current-turn GitHub data call. Primary gh path:

gh issue list --repo "$SOURCE_REPO" --state "$STATE" --limit "$LIMIT" \
  --json number,title,labels,assignees,url,body

Add optional filters only when present:

• --label "$LABEL"
• --milestone "$MILESTONE"
• --assignee "$ASSIGNEE" after resolving @me

API fallback path with gh still available:

gh api "repos/$SOURCE_REPO/issues" \
  -f state="$STATE" -f per_page="$LIMIT"

API fallback path without gh: call http_request with bearerSecretName: "GH_TOKEN" and the GitHub URL. Example request shape:

{
  "method": "GET",
  "url": "https://api.github.com/repos/{SOURCE_REPO}/issues?state={STATE}&per_page={LIMIT}",
  "bearerSecretName": "GH_TOKEN",
  "headers": {
    "Accept": "application/vnd.github+json"
  }
}

Add API query parameters only when present:

• labels=$LABEL
• assignee=$ASSIGNEE after resolving @me through GET /user
• milestone=$MILESTONE_NUMBER; if the user supplied a title, first list milestones and match the title to a number

gh issue list excludes pull requests. API issue endpoints include pull requests, so exclude any item with a pull_request field.

Hard failure rule: if the current turn did not execute a successful gh issue list, GitHub Issues API, or equivalent http_request call, do not display an issue table and do not say no issues matched. Report that live issue fetch did not complete.

If watch context includes PROCESSED_ISSUES, filter those issue numbers out. If no issues match, report that directly and, in watch mode, continue to Phase 6 to check review feedback.

Extract for each issue: number, title, body, label names, assignees, URL.

Phase 3 - Present And Confirm

Display a compact table:

If fork mode is active, also say that branches will be pushed to PUSH_REPO and PRs will target SOURCE_REPO.

If --dry-run is set, stop after the table. Do not run preflight.

If --yes is set, process every listed issue and proceed to Phase 4.

Otherwise ask:

Which issues should I process: all, a comma-separated list of issue numbers, or cancel?

Wait for the user response. Continue only with selected issue numbers.

Watch behavior: ask on the first interactive poll unless --yes is set. Do not schedule watch follow-up from a parse-only turn. After the user confirms issues or after a --yes run completes, schedule the next run in Watch Mode. Subsequent scheduled runs use --cron --yes.

Phase 4 - Issue Processing Preflight

Run this phase only after selected issue numbers are known. These checks are for delegating fixes, not for issue listing.

1. Resolve the local checkout.

   Use the current directory if it is a git repo whose origin matches SOURCE_REPO. If the current directory is not a matching checkout, ask the user for the local checkout path before processing. Issue listing does not require a local checkout, but fixing issues does.

2. Check the working tree.

   git status --porcelain

   If output is non-empty, explain that delegated fixes should start from a committed state and ask whether to continue. Never stage or commit unrelated changes.

3. Record the base branch.

   git rev-parse --abbrev-ref HEAD

   Store as BASE_BRANCH.

4. Verify remotes.

   git ls-remote --exit-code origin HEAD

   In fork mode, verify a fork remote exists for PUSH_REPO; add it only if missing, and use the normal GitHub remote URL. Do not write tokens into git config.

5. Skip issues that already have open PRs from the intended branch owner.

   gh pr list --repo "$SOURCE_REPO" --state open \
     --head "fix/issue-$ISSUE_NUMBER" \
     --json number,url,headRefName,headRepositoryOwner \
     --jq ".[] | select(.headRepositoryOwner.login == \"$PUSH_OWNER\")"

   If gh is unavailable, use http_request with bearerSecretName: "GH_TOKEN":

   {
     "method": "GET",
     "url": "https://api.github.com/repos/{SOURCE_REPO}/pulls?head={PUSH_OWNER}:fix/issue-{ISSUE_NUMBER}&state=open&per_page=1",
     "bearerSecretName": "GH_TOKEN",
     "headers": {
       "Accept": "application/vnd.github+json"
     }
   }

6. Skip issues whose intended branch exists in PUSH_REPO.

   BRANCH_REF="fix%2Fissue-$ISSUE_NUMBER"
   gh api "repos/$PUSH_REPO/branches/$BRANCH_REF" --silent

   If gh is unavailable, use http_request with bearerSecretName: "GH_TOKEN" against: https://api.github.com/repos/{PUSH_REPO}/branches/fix%2Fissue-N.

7. Track claims for cron/watch dedupe when durable state storage is available.

   Use $HYBRIDCLAW_STATE_DIR/gh-issues when that variable is set, otherwise $HOME/.hybridclaw/data/gh-issues. Create the directory if needed. Store claims in claims.json, creating it as {} if missing. Remove claims older than 2 hours. For each remaining issue, skip if key SOURCE_REPO#ISSUE_NUMBER is claimed. Never write claim or cursor files into the target repository checkout.

If all selected issues are skipped, report why and, in watch mode, continue to Phase 6.