Gh Fix Issue

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

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:

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

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

   ## 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.