debug-fix

name	debug-fix
description	Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)
argument-hint	[issue number, error message, or description of the problem]
disable-model-invocation	true

Find and fix the following issue:

Problem: $ARGUMENTS

Step 1: Understand the Problem

Determine what kind of input this is:

• Issue number → fetch it: gh issue view $ARGUMENTS (GitHub), or check the project's issue tracker
• Error message / stack trace → parse it for file, line, error type, and the call chain leading to it
• Description of behavior → identify what's expected vs what's happening
• URL / screenshot → examine the referenced resource

If the problem is unclear, ask clarifying questions before proceeding.

Step 2: Reproduce

• Find or write the simplest way to trigger the issue (a test, a curl command, a script)
• Confirm you can reproduce it reliably
• If you can't reproduce:
  • Environment-specific? Check env vars, OS, Node/Python version, database state
  • Intermittent? Likely a race condition — look for shared mutable state, timing dependencies, or async ordering assumptions
  • Already fixed? Check git log for recent commits that mention the issue

Step 3: Investigate

Follow this sequence — don't skip ahead to guessing:

1. Locate the symptom: which file and line produces the wrong output/error?
2. Read the code path: trace backwards from the symptom. What function called this? What data did it pass? Read each caller.
3. Check git history: git log --oneline -20 -- <file> to see what recently changed in the affected files. git log --all --grep="<keyword>" to find related commits.
4. Narrow the scope: use git bisect or targeted grep to identify when the behavior changed, or which input triggers it.
5. Form a hypothesis: "I think [X] is wrong because [evidence]."
6. Verify the hypothesis: add a targeted log/assertion/test that would confirm or deny it. Run it.
7. If wrong, update: don't keep guessing with the same hypothesis. Go back to step 2 and trace a different path.

Step 4: Fix

• Make the minimal change that fixes the root cause
• Don't patch symptoms — if a value is wrong, trace back to where it becomes wrong and fix it there
• Don't refactor surrounding code while fixing the bug
• Don't add defensive checks that mask the problem — fix why the bad data exists

Step 5: Verify

• Write a test that reproduces the original bug and now passes with the fix
• Run related tests to check for regressions
• Run lint and typecheck
• Temporarily revert your fix and confirm the new test fails — this proves the test actually catches the bug

Step 6: Wrap Up

• Create a branch if not already on one
• Stage only the relevant files (fix + test, nothing else)
• Commit with a message that references the issue if one exists: fix: <what was wrong and why> (#number)