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

| 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: `" | | "Consider fixing..." / "It looks like..." | "Action: Fix in " | | "Various errors are reported" | "2 error messages extracted: , " | | "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: \" |

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

# 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 "" --focus "src/lib"

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

# Limit comment length
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-issue/scripts/inspect_issue.py" --repo "." --issue "" --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.

1. Resolve the Issue.

• Accept issue number or full URL.
• Validate that the issue exists and is accessible.

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

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

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

1. Produce Issue Analysis Report (mandatory format).

Output MUST use this exact structure:

```text ## Issue Analysis Report: #

Issue Type: BUG | FEATURE | ENHANCEMENT | DOCUMENTATION | QUESTION | UNCLASSIFIED Title: State: OPEN | CLOSED Labels: , , ... Assignees: , , ... Actionable items:

---

### EXTRACTED CONTEXT

#### Error Messages

• ``
• ``

#### Stack Traces ```

```

#### File References

• path/to/file.ext:42 [EXISTS]
• path/to/other.ext:10 [NOT FOUND]

#### Repro Steps

#### Expected vs Actual

• Expected:
• Actual:

---

### CODEBASE MATCHES

#### M1.

• Path: path/to/file.ext:line
• Relevance: Why this file matters

#### M2. ...

---

### ACTIONABLE

#### A1. [CATEGORY]

• What: Factual statement (no speculation)
• Where: filepath:linenumber
• Evidence: Verbatim quote from issue or codebase
• Action: Specific fix (file path, command, or code change)
• Confidence: High | Medium | Low

#### A2. [CATEGORY] ...

---

### INFORMATIONAL

#### I1. [CATEGORY]

• What / Note

---

### LINKED CONTEXT

#### Linked PRs

• PR #: []

#### Cross-references

• #
• org/repo#

#### Comments Summary

• comments from authors
• Key points: ...

---

Summary: actionable items, informational items, 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

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

1. Post progress comment to the Issue.

• Use the Issue Progress Comment Template.
• Include analysis summary and planned actions.
• Command: gh issue comment -b ""

1. 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 #).
• 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 the issue, and checks file existence.

Arguments:

| Argument | Default | Description | |----------|---------|-------------| | --repo | . | Path inside the target Git repository | | --issue | (required) | Issue number or URL | | --focus | (none) | Codebase search narrowing area | | --max-comment-length | 0 (unlimited) | Max characters per comment body | | --json | false | Emit JSON output |

Exit codes:

• 0: Success
• 1: Error occurred

Features

Issue Data Fetching

Fetches comprehensive issue data:

• Title, body, state, labels, assignees, author
• All comments (with optional length truncation)
• Linked PRs via GraphQL timeline events (CrossReferencedEvent, ConnectedEvent)

Error Context Extraction

Parses issue body and comments for:

• Error messages (Error:, TypeError:, panicked at, etc.)
• Stack traces (at , Traceback, thread '...' panicked, etc.)
• File path references (path/to/file.ext:123 format)
• Fenced code blocks
• Well-known sections (Steps to Reproduce, Expected Behavior, Actual Behavior)
• Cross-references (#123, org/repo#123)

Issue Classification

Classifies based on labels (highest priority) and body/title heuristics:

• BUG: bug, defect, regression, crash, error labels or error indicators in body
• FEATURE: feature, feature-request labels or feature request language
• ENHANCEMENT: enhancement, improvement labels
• DOCUMENTATION: documentation, docs labels
• QUESTION: question, help, support labels or question language
• UNCLASSIFIED: No matching signals

File Existence Check

Validates extracted file references against the repository:

• Checks if files exist at the referenced paths
• Reports [EXISTS] or [NOT FOUND] status

Output Examples

Text Output

Issue #42: TypeError when clicking save button
============================================================
State: OPEN
Type: BUG
Labels: bug, ui
Assignees: developer1
Author: @reporter1
URL: https://github.com/org/repo/issues/42

BODY
------------------------------------------------------------
When I click the save button on the settings page, I get this error:

TypeError: Cannot read properties of undefined (reading 'name') at SaveHandler (src/components/Settings.tsx:42) at onClick (src/components/Button.tsx:15)

### Steps to Reproduce
1. Open Settings page
2. Change any setting
3. Click Save

### Expected Behavior
Settings should be saved successfully.

### Actual Behavior
TypeError is thrown and settings are not saved.

EXTRACTED SECTIONS
------------------------------------------------------------

[Steps To Reproduce]
1. Open Settings page
2. Change any setting
3. Click Save

[Expected]
Settings should be saved successfully.

[Actual]
TypeError is thrown and settings are not saved.

ERROR MESSAGES (1)
------------------------------------------------------------
  [1] TypeError: Cannot read properties of undefined (reading 'name')

STACK TRACES (1)
------------------------------------------------------------
  [1]
    at SaveHandler (src/components/Settings.tsx:42)
    at onClick (src/components/Button.tsx:15)

FILE REFERENCES (2)
------------------------------------------------------------
  src/components/Settings.tsx:42 [EXISTS]
  src/components/Button.tsx:15 [EXISTS]

COMMENTS (1)
------------------------------------------------------------
@maintainer1 (2025-01-20):
  This might be related to the recent refactor in #38.

LINKED PULL REQUESTS (1)
------------------------------------------------------------
  PR #45: Fix settings save handler [OPEN]
    https://github.com/org/repo/pull/45
============================================================

JSON Output

{
  "issue": {
    "number": 42,
    "title": "TypeError when clicking save button",
    "body": "...",
    "state": "OPEN",
    "labels": [{"name": "bug"}, {"name": "ui"}],
    "assignees": [{"login": "developer1"}],
    "author": {"login": "reporter1"},
    "url": "https://github.com/org/repo/issues/42"
  },
  "issueType": "BUG",
  "comments": [
    {
      "id": 123456,
      "author": "maintainer1",
      "body": "This might be related to the recent refactor in #38.",
      "createdAt": "2025-01-20T12:00:00Z"
    }
  ],
  "linkedPRs": [
    {
      "number": 45,
      "title": "Fix settings save handler",
      "state": "OPEN",
      "url": "https://github.com/org/repo/pull/45"
    }
  ],
  "parsed": {
    "errorMessages": [
      "TypeError: Cannot read properties of undefined (reading 'name')"
    ],
    "stackTraces": [
      "at SaveHandler (src/components/Settings.tsx:42)\n    at onClick (src/components/Button.tsx:15)"
    ],
    "fileReferences": [
      "src/components/Settings.tsx:42",
      "src/components/Button.tsx:15"
    ],
    "codeBlocks": ["TypeError: Cannot read properties of undefined..."],
    "sections": {
      "steps_to_reproduce": "1. Open Settings page\n2. Change any setting\n3. Click Save",
      "expected": "Settings should be saved successfully.",
      "actual": "TypeError is thrown and settings are not saved."
    },
    "crossReferences": [
      {"repo": "", "number": 38, "ref": "#38"}
    ]
  },
  "fileChecks": [
    {"reference": "src/components/Settings.tsx:42", "path": "src/components/Settings.tsx", "exists": true},
    {"reference": "src/components/Button.tsx:15", "path": "src/components/Button.tsx", "exists": true}
  ]
}

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: akiojin
• Source: akiojin/skills
• License: MIT

Install and usage instructions live in the source repository linked above.