| name | debug-fix |
| description | Find and fix a bug. Default is careful (reproduce, investigate, test). Add `--fast` for emergency production mode (hotfix branch, minimal change, ship a PR fast). |
| argument-hint | [issue, error, or description] [optional: --fast] |
| disable-model-invocation | true |
| allowed-tools | ["Bash(git *)","Bash(gh *)","Bash(npm run test *)","Bash(npm run build)","Read","Glob","Grep","Edit","Write"] |
Find and fix the following issue:
Problem: $ARGUMENTS
Mode
Check $ARGUMENTS for --fast. Strip it before parsing the problem description.
- Default: careful debug-fix. Use when you have time to do this right.
- --fast: emergency hotfix. Use when production is broken and shipping speed matters more than thoroughness. Triggers a
hotfix/* branch from production, minimal-change discipline, critical-tests-only verification, and ships a [HOTFIX] PR. Before committing to fast mode, briefly confirm with the user that this is genuinely emergency-grade. If not, suggest dropping --fast.
Step 1: Understand
- Issue number:
gh issue view $ARGUMENTS (or the project's issue tracker).
- Error or stack trace: parse it for file, line, error type, and call chain.
- Description: identify expected vs actual.
- URL or screenshot: examine the referenced resource.
If unclear, ask clarifying questions before proceeding.
Step 2: Hotfix branch (--fast only)
In --fast mode only:
- Detect the production branch:
git symbolic-ref refs/remotes/origin/HEAD or git remote show origin.
- Stash uncommitted work if needed.
- Create and switch to
hotfix/<short-description> branched from production.
- ASK the user to confirm the branch name first.
In default mode, skip this. Branch creation happens in Step 7.
Step 3: Reproduce (default only)
In --fast mode, skip this step. Trust the report and move to Step 5.
- Find the simplest way to trigger the issue (a test, curl, script).
- Confirm you can reproduce reliably.
- If you can't reproduce:
- Environment-specific? Check env vars, OS, runtime version, database state.
- Intermittent? Likely a race condition. Look for shared mutable state, timing dependencies, async ordering assumptions.
- Already fixed?
git log for recent commits mentioning the issue.
Step 4: Investigate (default only)
In --fast mode, skip this and go to Step 5. Trust the report and minimize investigation depth.
Don't skip ahead to guessing:
- Locate the symptom. Which file and line produces the wrong output?
- Read the code path backwards. What called this? What data was passed?
- Check git history:
git log --oneline -20 -- <file>, git log --all --grep="<keyword>".
- Narrow scope with
git bisect or targeted grep.
- Form a hypothesis: "X is wrong because Y."
- Verify the hypothesis with a targeted log or assertion.
- If wrong, trace a different path. Don't keep guessing the same hypothesis.
Step 5: Fix
- Make the smallest correct change.
- Don't patch symptoms. Trace back to where bad data originates and fix it there.
- Don't refactor surrounding code while fixing.
- Don't add defensive checks that mask the problem.
In --fast mode specifically:
- If the fix needs more than ~50 lines changed, warn the user. This may not actually be a hotfix.
- Do NOT add features, change formatting, clean up unrelated issues, or add non-essential comments.
Step 6: Verify
Default:
- Write a test that reproduces the bug and now passes.
- Run related tests for regressions.
- Run lint and typecheck.
- Temporarily revert your fix and confirm the new test fails (proves the test catches the bug).
--fast:
- Run only tests directly relevant to the changed code, not the full suite.
- Run the build.
- If you can reproduce the original error, verify it's fixed.
- ASK the user if they want extra verification before shipping.
Step 7: Wrap up or ship
Default:
- Create a branch if not already on one.
- Stage only the fix and test files.
- Commit:
fix: <what was wrong and why> (#number).
--fast:
- Stage only the fix files (never secrets, locks, or build output).
- Draft commit:
hotfix: <short description>. ASK the user to confirm.
- Push:
git push -u origin hotfix/<description>.
- Create a PR targeting production:
- Title:
[HOTFIX] <description>.
- Body: what broke, what caused it, what this fixes.
- Try to add the
hotfix label: gh pr create ... --label hotfix. Fall back to no label on failure.
- Show the PR URL.
Rules
- NEVER skip confirmation steps in
--fast mode (branch name, commit message, push).
- NEVER force-push.
- NEVER commit secrets or unrelated changes.
- If the user says "skip" at any step, skip and move on.
- In
--fast mode specifically: if the fix turns out to be complex, tell the user and suggest dropping --fast to use the careful path.
