---
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.