git-issue

When to Use This Skill

Context

• Git remotes: !git remote -v
• Current branch: !git branch --show-current
• Working tree clean: !git status --porcelain=v2

Open issues, open PRs, and available labels are fetched during execution (requires a configured git remote).

Parameters

Parse these parameters from the command:

Your Task

Process GitHub issues using a TDD workflow, cutting each issue's branch from origin/main.

Mode Detection

Step 0: Normalize issue references

Before counting tokens or detecting mode, normalize every non-flag token in $ARGUMENTS into a (number, repo) pair. Accept these forms, in any space- or comma-separated mix:

Rules:

1. Split on whitespace and commas; strip a leading #; strip a URL #... fragment after the number.
2. A token is an issue ref only if, after stripping, it is all digits or matches the /issues/<digits> URL shape (require trailing digits — a /pull/<N>, /discussions/<N>, or bare /issues list URL is not a ref). Leave --flag tokens and their values (e.g. --filter bug,enhancement) untouched — never split a flag's comma-separated value into refs.
3. For a URL whose <owner>/<repo> differs from the current remote (Context git remote -v), record it as cross-repo and carry -R <owner>/<repo> on every gh call for that issue (gh issue view <N> -R …, gh api repos/<owner>/<repo>/…, gh pr edit … -R …). PR creation for a cross-repo issue needs a branch in that repo — if the current checkout is not that repo, surface it with AskUserQuestion rather than pushing to the wrong remote.
4. After normalization, dedupe and count refs: 0 → No-Arguments interactive; 1 → Single; ≥2 → Multiple.

No Arguments → Interactive Mode

Use AskUserQuestion to prompt:

questions:
  - header: "Issues"
    question: "How would you like to select issues to work on?"
    options:
      - label: "Let me choose specific issues"
        description: "Show issue list for manual selection"
      - label: "Claude decides priority"
        description: "Analyze issues and recommend which to tackle"
      - label: "Filter by label"
        description: "Select issues with a specific label"

For "Let me choose specific issues":

1. Fetch: gh issue list --state open --json number,title,labels,assignees
2. Present checkboxes with multiSelect: true

For "Claude decides priority":

• Analyze all open issues
• Score by clarity, scope, dependencies
• Present top recommendations

For "Filter by label":

• Present label selection from available labels
• Then show matching issues for selection

Single Issue (/git:issue 123)

Process directly with standard TDD workflow.

Multiple Issues (/git:issue 123 456 789)

1. Analyze all issues for conflicts and parallelization
2. Group by dependencies
3. Process sequentially or spawn parallel agents

Auto Mode (/git:issue --auto)

1. Fetch all open issues
2. Score and prioritize
3. Present recommendations for approval
4. Process approved issues

Issue Analysis Engine

Before processing multiple issues, run the blocker check, conflict detection, confidence scoring, and parallel-work detection described in REFERENCE.md. Never silently work on a blocked issue, and surface a sub-70% confidence score to the user rather than guessing.

Execution Workflow

Step 1: Prepare Working Directory

1. Ensure clean working directory (commit or stash if needed)
2. Fetch the remote: git fetch origin — never rely on local main being current

Step 2: For Each Issue (or Parallel Group)

Standard Flow (Sequential or Single Issue)

1. Fetch issue details AND the comment thread: gh issue view $N --json title,body,state,assignees,labels,comments The comments field is not optional — the body is the opening position, not the decision. Scope from git-plugin:git-issue-scoping, which carries the full protocol (re-verify cited evidence at HEAD; a later comment may have narrowed, reversed, or already resolved the ask).
2. Capture issue labels for later PR creation
3. Identify requirements and acceptance criteria
4. Plan the implementation approach
5. Cut the branch from origin/main: git switch -c fix/issue-$N origin/main

Base the branch on origin/main, never on local main — local main may carry unpushed commits that would ride into this issue's PR (see git-branch-pr-workflow § "Branch Comparison: Always Use origin/main").

TDD Workflow

1. RED phase: Write failing tests first

   • Create test file if needed
   • Write tests that define expected behavior
   • Run tests to verify they fail

2. GREEN phase: Implement fix

   • Write minimal code to make tests pass
   • Run tests to verify they pass

3. REFACTOR phase: Improve code quality

   • Clean up implementation
   • Ensure tests still pass

Commit and Push

1. Stage changes: git add -u and git add <new-files>
2. Run pre-commit if configured
3. Commit on the issue branch with message format:

<type>: <description>

<optional body explaining the change>

Fixes #N

4. Verify the branch carries only this issue's commits: git log --oneline origin/main..HEAD
5. Push the issue branch: git push -u origin fix/issue-$N

Create PR

Use mcp__github__create_pull_request with:

• head: fix/issue-$N
• base: main
• title: From issue title with fix: prefix
• body: Include Fixes #$N to auto-link

After PR creation, apply labels:

gh pr edit <pr-number> --add-label "<labels>"

Step 3: Parallel Execution (--parallel flag)

When --parallel is specified:

1. Group issues by dependencies (from analysis)
2. For each parallel group, spawn a Task agent:

Agent tool with subagent_type: "general-purpose", prompt: "Process issue #N with TDD workflow.
Cut the branch with `git fetch origin && git switch -c fix/issue-N origin/main` — never from local main..."

Give the subagent the issue's title and body verbatim (quoted, not summarised) and the labels to apply, and instruct it to read the full comment thread itself — gh issue view N --json title,body,comments — before planning, scoping from the latest deciding comment rather than from your description of it. Do not restate the scope in your own words: the subagent implements what the thread decided, not what you paraphrased.

3. Wait for all agents to complete
4. Consolidate results

Workflow harness (template)

workflows/issue-group-wave.workflow.js ships beside this skill and covers the --parallel path only. It is a TEMPLATE to adapt, not a script to run verbatim. Read it, then rewrite it for the work in front of you.

Adapt freely: the grouping and implementation agent prompts, the default wave width, the conflict heuristics, the deferral vocabulary, and the project-specific test and commit commands.

Preserve across any adaptation: (a) the loop bound is args.issues — the refs Step 0 normalised — and the grouping agent partitions that set, never extends it: the template validates the returned partition against the input, discards invented issues, keeps the first placement of a duplicate, and re-dispatches an omitted issue standalone rather than dropping it; (b) the GROUP_SCHEMA shape, where every input issue lands in exactly one group or in deferred with a closed blocked|low-confidence|cross-repo|not-open reason, plus IMPL_SCHEMA's implemented|no-change|failed outcome — so "skipped it" is not expressible, and an issue already fixed at HEAD stays distinguishable from a failed one; (c) the Group stage is a real barrier — conflict detection is pairwise over the whole set (file overlap, opposing requirements, blocked_by chains, sub-issue ordering), so no group can be dispatched until every issue has been read, and you cannot partition work by a partition the work itself discovers, which is why the grouping lane is always ONE agent.

Skip the harness when: a single issue was supplied — the modal case — or the partition collapses to one group because every issue conflicts with every other; that is a linear pass and the harness is pure overhead (the template aborts below two issues, and returns the partition rather than dispatching when only one group survives). The steps above remain the authoritative description of what each stage must produce; the harness only fixes how the work is split.

One thing the harness changes rather than splits: AskUserQuestion cannot run inside a workflow, so the blocked-issue and sub-70%-confidence prompts above become deferrals the caller adjudicates — the issue is neither silently attempted nor silently dropped.

Two clauses this template carries. Both are unconditional here — every fanned-out group runs in its own worktree, and this skill's deliverable is a PR:

Never Workflow({resumeFromRunId}) to retry a few failed worktree agents — a resume re-runs agents that already succeeded and opens duplicate PRs (#1868). Re-dispatch the failed units fresh and sequentially after checking gh pr list --head <branch> --state all --json number,state.

Push and PR creation happen only in the single sequential finalise stage, never inside a fanned-out agent. Under the harness the Execution Workflow's "Commit and Push" and "Create PR" steps move there: each agent commits on fix/issue-<n> inside its own worktree, and the returned finalisePlan is what the orchestrator pushes and opens PRs from, one at a time.

Summary Report

After processing, report the issues processed, PRs created, conflicts detected, and issues skipped — see REFERENCE.md for the table shape.

Resuming work on an existing PR branch

When a follow-up request continues an issue whose branch already has a PR, invoke /git:pr-sync-check before adding commits. A pr_merged verdict means the PR already landed — start a fresh branch off the updated default rather than building on the merged branch; a behind verdict means a teammate / agent / CI auto-fix pushed under you, so reconcile first. See .claude/rules/pr-branch-sync.md.

See Also

• git-pr-sync-check skill to confirm a PR branch is live and in sync before building on it
• git-branch-pr-workflow skill for workflow patterns
• test-tier-selection skill for test strategy
• git-cli-agentic skill for optimized git commands
• gh-cli-agentic skill for optimized GitHub CLI commands

For the issue-analysis heuristics (blocker check, conflict detection, confidence scoring, parallel-work detection), commit-message formats, the branch-from-remote pattern, and the summary-report table, see REFERENCE.md.