/debug-fix

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:

1. Locate the symptom. Which file and line produces the wrong output? 2. Read the code path backwards. What called this? What data was passed? 3. Check git history: `git log --oneline -20 -- <file>`, `git log --all --grep="<keyword>"`. 4. Narrow scope with `git bisect` or targeted grep. 5. Form a hypothesis: "X is wrong because Y." 6. Verify the hypothesis with a targeted log or assertion. 7. 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.