Fix GitHub Issue

A structured workflow for analyzing, fixing, and submitting a PR for a GitHub issue. This skill uses the GitHub CLI (gh) for all GitHub interactions.

Workflow

1. Understand the Issue

• Run gh issue view <number> to get full issue details (title, body, labels, comments)
• Read through the problem description carefully
• If the issue is unclear or missing key details, ask the user clarifying questions before proceeding

2. Research Prior Art

Before jumping into code, gather context — understanding what's been tried or discussed prevents duplicate work and surfaces useful patterns:

• Search the codebase for files and functions related to the issue
• Check if related PRs exist with gh pr list --search "<keywords>"
• Look for scratchpads or notes from previous investigation
• Read relevant source files to understand the current behavior

3. Plan the Fix

Think through how to break the issue into small, manageable tasks. Document your plan in a scratchpad file:

• Name the file descriptively (include the issue reference)
• Include a link back to the issue
• List the specific changes needed and their order
• Note any risks or edge cases

4. Implement

• Create a new branch for the issue (e.g., fix/issue-123-description)
• Work through the plan in small steps
• Commit after each meaningful change — small commits are easier to review and revert

5. Test

Thorough testing prevents the fix from introducing new problems:

• Write unit tests that describe the expected behavior
• Run the full test suite to catch regressions
• If UI changes were made and browser automation (e.g., Puppeteer MCP) is available, use it to verify visually
• Fix any failing tests before moving on

6. Open Pull Request

• Push the branch and open a PR with gh pr create
• Reference the issue in the PR description (e.g., "Fixes #123")
• Request a review

gh Command Reference

# View issue details
gh issue view 123

# Create a branch
git checkout -b fix/issue-123-description

# Open a PR that closes the issue
gh pr create --title "Fix: description" --body "Fixes #123"

# Request review
gh pr edit 456 --add-reviewer username