Bugfix

Autonomous end-to-end bug fix: diagnose from evidence, find root cause, minimal fix, verify, commit.

NEVER

• Never ask the user for more information unless the bug description is completely ambiguous — use tools to find it.
• Never refactor unrelated code while fixing a bug — scope creep breaks regression isolation.
• Never fix other bugs you notice while fixing the target — create a new task instead.
• Never git add -A — stage only the files you changed.
• Never skip running the full workspace test suite after a fix — targeted test passing doesn't mean no regression.
• Never commit until typecheck passes on the affected workspace.

Root Cause Classification (decide before writing any code)

| Type | Signal | Fix approach | |------|--------|--------------| | Code bug | Logic error, wrong query, bad comparison | Fix implementation | | Test bug | Expectation contradicts documented contract | Fix the test — explain why it was wrong | | Mock wiring | mockReset: true pattern not followed, stale mock state | Use correct mock pattern from CLAUDE.md | | Type error | TypeScript compilation failure | Fix types, not tests | | Import error | Wrong package path, missing export | Fix import resolution |

If it's a mock wiring issue: read the mock patterns in CLAUDE.md before writing anything — there are three distinct patterns (forwarding, object-bag, counter-based sequencing).

Evidence-First Thinking

Collect before hypothesizing:

1. Run the failing test — see the exact error output, not just the description
2. Read the failing test — understand what it expects
3. Read the source under test
4. git log --oneline -10 -- <file> — was this recently changed?
5. For runtime errors: check logs, route/plugin/service code

State hypothesis explicitly before writing code: "The test fails because X, caused by Y."

Abort Conditions (stop and ask user)

• Bug is in security-sensitive area (auth, RBAC, IDOR) — confirm fix approach first
• Fix requires changing more than 5 files — may be an architectural issue
• Root cause requires changing the mock strategy for an entire test suite

Scripts

bash scripts/collect-bugfix-context.sh apps/api/src/tests/routes/auth.test.ts
bash scripts/run-targeted-test.sh apps/api/src/tests/routes/auth.test.ts
bash scripts/run-targeted-test.sh apps/api/src/tests/routes/auth.test.ts "returns 500"

Verification Sequence

1. Run the specific failing test — must pass
2. Run the full workspace suite — no new failures
3. Run typecheck on the affected workspace (npx tsc --noEmit)
4. git diff --name-only — verify every changed file relates to the bug; revert anything that doesn't

Commit Format

fix(scope): what was broken and how it was fixed

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Arguments

$ARGUMENTS: Error message, failing test path, CI log URL, or reproduction steps. If empty, ask for the error or failing test name.