| name | bugfix |
| description | "Use when given a bug report, failing test, stack trace, or CI failure that needs diagnosis and repair. Autonomously diagnoses root cause, implements minimal fix, verifies correctness, and commits. Keywords: fix bug, failing test, stack trace, CI failure, debug error, broken test. Triggers on "fix bug" or "debug failing test"." |
Bugfix
When to Use
Load this skill when the user request matches the frontmatter description for 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:
- Run the failing test — see the exact error output, not just the description
- Read the failing test — understand what it expects
- Read the source under test
git log --oneline -10 -- <file> — was this recently changed?- 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
- Run the specific failing test — must pass
- Run the full workspace suite — no new failures
- Run typecheck on the affected workspace (
npx tsc --noEmit)
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.
