Test-First Bugfix
Force your agent to reproduce every bug with a failing test before fixing it.
An agent skill enforcing the single highest-leverage debugging discipline: write a failing test that reproduces the bug BEFORE touching the fix. Prevents the classic agent failure of 'fixing' symptoms while the real bug survives, and leaves a regression test behind every time.
SKILL.md
--- name: test-first-bugfix description: Reproduce bugs with a failing test before fixing. Use whenever fixing a reported bug. --- # Test-First Bugfix When asked to fix a bug, NEVER edit production code first. Follow this sequence: ## 1. Reproduce - Write the smallest test that exercises the reported behavior - Run it and confirm it FAILS for the reported reason - If it passes, the bug is elsewhere — report this and investigate before writing any fix - If reproduction needs unavailable state (prod data, external service), write the test with a fake/fixture and state the assumption ## 2. Fix - Make the minimal change that turns the test green - Run the FULL test suite for the affected package, not just the new test - If other tests break, understand why before adjusting them — a broken test may be pinning behavior someone depends on ## 3. Verify & report - Show the test failing before and passing after (paste both outputs) - State what the root cause was in one sentence - The regression test stays in the suite — never delete it after fixing ## Anti-patterns (refuse these) - "Just add a null check" without understanding why the value is null - Broadening a try/catch to make a symptom disappear - Marking a test as skipped to get CI green
How to use
- 1Save as .claude/skills/test-first-bugfix/SKILL.md.
- 2Triggered automatically when you ask the agent to fix a bug; you can also invoke it explicitly.
- 3When the agent reports 'the test passed unexpectedly', treat it as a finding — your bug report may point at the wrong component.
- 4Combine with a CI rule that new fixes must include a test touching the changed lines.
Examples
Fixing an off-by-one in pagination
Input
User reports page 2 shows the last item of page 1 again.
Output
Step 1: wrote `test_page_boundaries` asserting items 10-19 on page 2 — FAILS: item 9 returned. Root cause: offset computed as `page * size - 1`. Step 2: fixed offset arithmetic; full suite green (214 passed). Regression test kept.
Pro tips
- The 'test passed unexpectedly' path catches misdiagnosed bugs surprisingly often — read those reports carefully.
Frequently asked questions
Doesn't this slow the agent down?+
Each fix takes a few minutes longer and reverts far less often. The expensive failure mode this prevents — plausible fixes that don't address the real cause — typically costs a full re-investigation later.
What about bugs that are hard to test, like UI glitches?+
The skill's fixture rule covers most cases (fake timers, snapshot the DOM state). For genuinely untestable issues, the agent states the assumption explicitly instead of silently skipping the discipline.