git-issue

What this skill does

## 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 |
|-----------|-------------|
| `<issue-numbers...>` | One or more issue numbers to process |
| `--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

### No Arguments → Interactive Mode

Use AskUserQuestion to prompt:

```yaml
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:

```bash
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:

```yaml
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:
```bash
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

```bash
# 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 featur