debug-fix

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.