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, analyze for:

Blocker Check (run first)

Before sequencing or scoring, ask GitHub which issues are blocked by other open work via the native dependencies API:

gh api repos/$OWNER/$REPO/issues/$N/dependencies/blocked_by \
  --jq '.[] | select(.state == "open") | .number'

If the list is non-empty:

1. Report the open blockers inline: #N is blocked by #X, #Y.
2. Use AskUserQuestion to offer: work on a blocker first, skip this issue, or proceed anyway (only appropriate if the blocker is stale or mis-linked).
3. Never silently work on a blocked issue — the "Blocked" badge exists so humans don't ship work out of order.

Also fetch dependencies/blocking to understand downstream impact — finishing an issue that blocks others may be higher leverage than finishing an independent issue of the same size.

Conflict Detection

Identify issues that cannot be worked on simultaneously:

Confidence Scoring

Score each issue's implementability:

Threshold: 70%

If confidence < 70%, prompt user:

questions:
  - header: "Low confidence"
    question: "Issue #N has unclear requirements. How should I proceed?"
    options:
      - label: "Attempt anyway"
        description: "Make best-effort attempt based on available info"
      - label: "Ask for clarification"
        description: "Request more details on the issue"
      - label: "Skip this issue"
        description: "Move to next issue in queue"

Parallel Work Detection

Identify issues that can be worked simultaneously:

Parallelizable when:

• Different files/components
• Neither issue appears in the other's dependencies/blocked_by
• Neither is a sub-issue of the other
• Independent test suites
• No logical conflicts

Output format:

Parallel Groups:
  Group 1: #123, #125 (both touch auth module - sequential)
  Group 2: #124 (standalone - can run in parallel)
  Group 3: #126, #127 (both touch UI - sequential)

Recommended: Run Groups 1, 2, 3 in parallel (3 agents)

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

Commit Message Format

Issue reference at BOTTOM:

<type>: <description>

<optional body explaining the change>

Fixes #123

Multiple issues in single commit:

fix: resolve authentication and session handling

- Add token refresh logic
- Fix session timeout detection

Fixes #123
Fixes #125

Branch-From-Remote Pattern

Cut every issue branch from origin/main, never from local main:

git fetch origin
git switch -c fix/issue-$N origin/main

# ... make changes, commit on the branch ...

git log --oneline origin/main..HEAD    # verify: only your commit(s)
git push -u origin fix/issue-$N

# Create PR: head=fix/issue-$N, base=main
# Next issue: git fetch origin && git switch -c fix/issue-$M origin/main

Why not commit on local main: unpushed commits on local main ride into the next branch cut from it and land in an unrelated PR — visible only in the file list once squashed. Basing on origin/main makes the local main state irrelevant. This matches git-branch-pr-workflow § "Branch Comparison: Always Use origin/main" (rule 3: base PRs on origin/main when creating branches) and ~/.claude/rules/git-hazards.md #2.

Summary Report

After processing, report:

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