# Git Issue

> GitHub issue to PR end-to-end — branch, TDD implementation, PR — one issue or several in parallel. Use when asked to work on an issue, fix issue #N, or batch-process several.

- Skill: `laurigates/git-issue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add laurigates/git-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laurigates/git-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: laurigates (https://skillmd.com/u/laurigates)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/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, 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:

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

```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. **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:
```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.
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`:

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

| 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