laurigates/git-issue

When to Use This Skill

| Use this skill when... | Use X instead when... | |------------------------|----------------------| | Implementing a fix for one or more open issues with TDD and PR creation | Performing administrative ops (transfer, pin, lock, bulk edit) on issues (/git:issue-manage) | | Picking issues from the backlog to work on, optionally in parallel | Periodically grooming open issues and PRs to close stale or completed ones (/git:triage) | | Going from an issue number to a merged-ready PR end-to-end | Hierarchical sub-issue planning and tracking (/git:issue-hierarchy) |

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:

| Parameter | Description | |-----------|-------------| | <issues...> | One or more issues as bare numbers, #N, or full GitHub issue URLs (https://github.com/<owner>/<repo>/issues/<N>), in any space- or comma-separated mix (see Step 0) | | --auto | Claude selects and prioritizes issues | | --filter <label> | Filter issues by label | | --limit <n> | Maximum number of issues to process | | --parallel | Process parallel groups simultaneously using Task agents | | --labels <label1,label2> | Apply labels to created PRs (defaults to issue's labels) |

Your Task

Process GitHub issues using a TDD workflow with the main-branch development pattern.

---

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:

| Input form | Extract | |------------|---------| | 123 | number 123, repo = current remote | | #123 | number 123, repo = current remote | | https://github.com/<owner>/<repo>/issues/123 | number 123, repo = <owner>/<repo> | | .../issues/123#issuecomment-... | number 123 (drop the #... fragment), repo = <owner>/<repo> |

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:

| Conflict Type | Detection Method | |---------------|------------------| | File overlap | Issues referencing same files/components | | Logical conflicts | Opposing requirements (add vs remove) | | Dependency chains | dependencies/blocked_by returns an open issue | | Sub-issue ordering | Parent's sub_issues not yet complete |

Confidence Scoring

Score each issue's implementability:

| Factor | Weight | Criteria | |--------|--------|----------| | Clear requirements | 30% | Has acceptance criteria, specific details | | Scope definition | 25% | Bounded scope, identifiable files | | No conflicts | 20% | No overlapping work with other issues | | Test strategy clear | 15% | TDD approach is obvious | | Labels/priority | 10% | Has priority labels, milestone |

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. Switch to main and pull latest: git switch main && git pull

Step 2: For Each Issue (or Parallel Group)

Standard Flow (Sequential or Single Issue)

1. Fetch issue details: gh issue view $N --json title,body,state,assignees,labels
2. Capture issue labels for later PR creation
3. Identify requirements and acceptance criteria
4. Plan the implementation approach

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 main with message format:

<type>: <description>

<optional body explaining the change>

Fixes #N

4. Push to remote issue branch: git push origin main: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..."

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

---

Main-Branch Development Pattern

# All work stays on main
git switch main && git pull

# ... make changes, commit on main ...

git push origin main:fix/issue-$N    # Push to remote feature branch

# Create PR: head=fix/issue-$N, base=main
# Continue on main for next issue

---

Summary Report

After processing, report:

| Metric | Details | |--------|---------| | Issues processed | List of issue numbers | | PRs created | PR numbers with links | | Conflicts detected | Issues that were sequentialized | | Issues skipped | Low confidence or user choice |

---

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