/fix-issue

Analyze and fix GitHub issue #$ARGUMENTS.

Argument validation

• Ensure an issue number was provided and prompt the user if not.

Context

• Issue (JSON): gh issue view "$ARGUMENTS" --json number,title,body,url,labels,assignees,state,author,createdAt,updatedAt
• Issue (human): gh issue view "$ARGUMENTS"
• Current branch: git branch --show-current
• Git status: git status -sb
• Open PRs referencing #$ARGUMENTS: gh pr list --state open --search "$ARGUMENTS in:title,body" --json number,title,url,headRefName,author

Inputs

• $ARGUMENTS = issue number (required)
• Type and branch slug are auto-inferred from the issue (no additional args).

Your task

1. Analysis and Clarification (use subagent)

   • Launch a general-purpose subagent to analyze the issue and gather requirements
   • The subagent should:
     • Read and summarize the issue: problem, acceptance criteria, scope, and risks
     • Identify any ambiguities or missing information
     • Use the AskUserQuestion tool to ask structured clarifying questions about:
       • Edge cases and error handling requirements
       • Scope boundaries (what's in/out of scope)
       • Implementation approach preferences
       • Testing expectations and coverage requirements
       • Any missing acceptance criteria
       • Breaking changes or migration concerns
     • Return a comprehensive summary including user responses
   • Wait for the subagent to complete and review the analysis before proceeding

2. Plan (propose and wait for confirmation)

   • Based on the analysis and clarification responses, propose a minimal, testable plan (files to change, tests to add, migration notes if any).
   • Post the proposed plan to the issue:
     • Create temp file: gh issue comment $ARGUMENTS --edit-last --body-file /dev/null 2>/dev/null || true (to get template if available)
     • Write plan to temp file: Use Write tool to create /tmp/claude/issue-comment-$ARGUMENTS.md with the concise plan summary
     • Use Read tool to verify the content if needed
     • Post comment: gh issue comment $ARGUMENTS --body-file /tmp/claude/issue-comment-$ARGUMENTS.md
   • Wait for user confirmation before making repo changes.

3. Branch management

   • If on main or default branch, create a branch:
     • Type: infer from labels/title (fix|feat|chore|docs|refactor). Default: fix.
     • Slug: derive from issue title (kebab-case, <=50 chars). Fallback: "issue-$ARGUMENTS".
     • Branch name: {type}/issue-$ARGUMENTS-{slug}
   • Commands to use (after approval):
     • git switch -c {branch} OR git checkout -b {branch}

4. Code search and implementation

   • Identify impacted modules and cross-cutting concerns.
   • Implement the fix/feature with small, logical commits.

5. Tests and local verification

   • Prefer unit tests. If integration tests needed, call that out.
   • Heuristics:
     • If package.json exists: run npm run check:all and npm test if available.
     • If a Python project: run uvx pytest and ruff if configured.
     • If Go: run go test ./....
   • Ensure dev server on port 3000 is not already running before starting any local server.

6. Quality gates

   • Ensure code passes linting, formatting, and type checks available in the repo.
   • Keep changes minimal and well-scoped.

7. Commit

   • Use a conventional commit message; include issue reference.
   • Example: "<type>: <scope>: <subject> (#$ARGUMENTS)" (type inferred)
   • Do NOT attribute to Claude in the commit message.

8. PR (draft) with Problem/Solution format

   • Push branch and create a draft PR that links the issue:
     • Write PR body to temp file using Write tool at /tmp/claude/pr-body-issue-$ARGUMENTS.md:

       ## Problem
       
       [Describe what's broken or missing]
       
       ## Solution
       
       [Explain what changed and why]
       
       ## Testing
       
       [How to test these changes]
       
       Fixes #$ARGUMENTS
       

     • Use Edit tool to update the temp file with actual problem/solution descriptions
     • Use Read tool to verify the content before creating PR
     • Create PR: gh pr create --draft --title "<type>(<scope>): <subject> (#$ARGUMENTS)" --body-file /tmp/claude/pr-body-issue-$ARGUMENTS.md

Notes

• Use GitHub CLI (gh) for all GitHub operations.
• Keep interactions idempotent and ask for confirmation before pushing or creating PRs.
• If repo tooling is unclear, ask whether to enable/add tests or linters for this fix.