gh-fix-issue

What this skill does

# Gh Fix Issue

## Overview

Use gh to inspect a GitHub Issue and:

- Fetch issue metadata (title, body, state, labels, assignees)
- Fetch all comments
- Fetch linked PRs via timeline events
- Extract error messages, stack traces, file references, code blocks, and cross-references
- Classify issue type (BUG / FEATURE / ENHANCEMENT / DOCUMENTATION / QUESTION)
- Search the codebase for relevant files
- Propose a fix plan with confidence levels

Then produce a structured Issue Analysis Report, post progress to the issue, and implement fixes after explicit approval.

- Depends on the `plan` skill for drafting and approving the fix plan.

Prereq: ensure `gh` is authenticated (for example, run `gh auth login` once), then run `gh auth status` with escalated permissions (include repo scope) so `gh` commands succeed.

## Analysis Report Anti-Patterns

### Prohibited Language

| Prohibited | Required Alternative |
|---|---|
| "We should look into..." | "Edit `path/file.ts:42` to..." |
| "There seem to be some issues" | "3 actionable items detected" |
| "This might be causing..." | "Root cause: `<error from issue>`" |
| "Consider fixing..." / "It looks like..." | "Action: Fix `<what>` in `<where>`" |
| "Various errors are reported" | "2 error messages extracted: `<msg1>`, `<msg2>`" |
| "Some files are involved" | "3 file references: `src/a.ts:42`, `src/b.rs:10`, `src/c.py`" |
| "I'll try to fix this" | "Action: \<specific fix\>" |

### Structural Prohibitions

- Prose paragraphs for reporting — use A1/I1 item format exclusively.
- Omitting the Evidence field in any ACTIONABLE item.
- Combining multiple independent problems into a single item.
- Omitting file paths or line numbers when the script output contains them.

## Issue/PR Comment Formatting (must follow)

- Final comment text must not contain escaped newline literals such as `\n`.
- Use real line breaks in comment bodies. Do not rely on escaped sequences for formatting.
- Before posting (`gh issue comment`), verify the final body does not accidentally include escaped control sequences (`\n`, `\t`).
- If a raw escape sequence must be shown for explanation, include it only inside a fenced code block and clarify it is intentional.

## Issue Progress Comment Template (required)

When posting progress updates to the issue, use this template:

```markdown
Progress
- ...

Done
- ...

Next
- ...
```

- Post updates at least when starting work, after meaningful progress, and when blocked/unblocked.
- In `Next`, explicitly state blockers or the immediate next action.

## Inputs

- `repo`: path inside the repo (default `.`)
- `issue`: Issue number or URL (required)
- `focus`: codebase search narrowing (optional; e.g., `src/lib/components`)
- `max-comment-length`: max characters per comment body (0 = unlimited)
- `gh` authentication for the repo host

## Quick start

```bash
# Inspect issue (text output)
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "<number>"

# Inspect issue by URL
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "https://github.com/org/repo/issues/123"

# With focus area
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "<number>" --focus "src/lib"

# JSON output
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "<number>" --json

# Limit comment length
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "<number>" --max-comment-length 500
```

## Workflow

1. **Verify gh authentication.**
   - Run `gh auth status` in the repo with escalated scopes (repo).
   - If unauthenticated, ask the user to log in before proceeding.

2. **Resolve the Issue.**
   - Accept issue number or full URL.
   - Validate that the issue exists and is accessible.

3. **Run inspect_issue.py to fetch and parse data.**
   - Fetch issue metadata, comments, and linked PRs.
   - Parse body and comments for error messages, stack traces, file references, code blocks, sections, and cross-references.
   - Classify the issue type.
   - Check file existence for extracted file references.

4. **Classify the Issue.**
   - Use labels (highest priority) and body/title heuristics.
   - Classification: BUG, FEATURE, ENHANCEMENT, DOCUMENTATION, QUESTION, UNCLASSIFIED.
   - BUG issues proceed to fix planning; FEATURE/ENHANCEMENT proceed to implementation planning.

5. **Search the codebase for relevant context.**
   - Use extracted file references as starting points.
   - Search for error messages and symbols mentioned in the issue.
   - If `--focus` is provided, restrict search to that area.
   - Use Grep/Glob to find related files and definitions.

6. **Produce Issue Analysis Report (mandatory format).**

   Output MUST use this exact structure:

   ```text
   ## Issue Analysis Report: #<number>

   **Issue Type:** BUG | FEATURE | ENHANCEMENT | DOCUMENTATION | QUESTION | UNCLASSIFIED
   **Title:** <issue title>
   **State:** OPEN | CLOSED
   **Labels:** <label1>, <label2>, ...
   **Assignees:** <assignee1>, <assignee2>, ...
   Actionable items: <N>

   ---

   ### EXTRACTED CONTEXT

   #### Error Messages
   - `<error message 1>`
   - `<error message 2>`

   #### Stack Traces
   ```
   <stack trace>
   ```

   #### File References
   - `path/to/file.ext:42` [EXISTS]
   - `path/to/other.ext:10` [NOT FOUND]

   #### Repro Steps
   <extracted Steps to Reproduce section>

   #### Expected vs Actual
   - **Expected:** <extracted expected behavior>
   - **Actual:** <extracted actual behavior>

   ---

   ### CODEBASE MATCHES

   #### M1. <file or symbol>
   - **Path:** `path/to/file.ext:line`
   - **Relevance:** Why this file matters

   #### M2. <file or symbol>
   ...

   ---

   ### ACTIONABLE

   #### A1. [CATEGORY] <1-line title>
   - **What:** Factual statement (no speculation)
   - **Where:** file_path:line_number
   - **Evidence:** Verbatim quote from issue or codebase
   - **Action:** Specific fix (file path, command, or code change)
   - **Confidence:** High | Medium | Low

   #### A2. [CATEGORY] <1-line title>
   ...

   ---

   ### INFORMATIONAL

   #### I1. [CATEGORY] <1-line title>
   - **What / Note**

   ---

   ### LINKED CONTEXT

   #### Linked PRs
   - PR #<number>: <title> [<state>]

   #### Cross-references
   - #<number>
   - org/repo#<number>

   #### Comments Summary
   - <N> comments from <M> authors
   - Key points: ...

   ---

   **Summary:** <N> actionable items, <M> informational items, <K> codebase matches.
   ```

   **Category labels:** `CODE-FIX`, `CONFIG-FIX`, `TEST-FIX`, `DEPENDENCY`, `DOCUMENTATION`, `DESIGN-DECISION`, `INVESTIGATION`

   **Confidence judgment:**

   - **High** — Clear error with obvious fix location, stack trace points to exact line
   - **Medium** — Error pattern matches but fix location needs investigation
   - **Low** — Requires design decision or the root cause is unclear

7. **Decide execution path based on Confidence.**
   - If ALL actionable items have Confidence: High → display report, propose plan, proceed after approval.
   - If ANY actionable item has Confidence: Low → request user guidance for low-confidence items before planning.
   - For FEATURE/ENHANCEMENT types → always create a plan and request approval.

8. **Post progress comment to the Issue.**
   - Use the Issue Progress Comment Template.
   - Include analysis summary and planned actions.
   - Command: `gh issue comment <number> -b "<body>"`

9. **Implement fixes after approval.**
   - Apply the approved fixes, summarize diffs/tests.
   - After applying fixes, commit changes and push.
   - Create or update a PR linking to the issue (e.g., `Fixes #<number>`).
   - Post a final progress comment to the issue.

## Bundled Resources

### scripts/inspect_issue.py

GitHub Issue inspection and analysis tool. Fetches issue data, parses error context, classifies