| name | failing-test-first |
| description | Reproduce a bug with a failing test before fixing it, so the fix is proven and can't silently regress. Use when the user reports a bug, says "this is broken", "X returns the wrong value", "fix this crash", or hands over a stack trace or a failing case. Write the smallest test that fails for the stated reason, then fix until it passes — and only it changes from red to green.
|
Failing Test First
A fix you can't see fail first is a guess. Capture the bug as a test, watch it fail for the right reason, then make it pass.
Steps
- Pin the defect. From the report, state the exact broken behavior: given this input/action, the code does X but should do Y. If you can't state it precisely, gather the missing detail (input, repro steps, error) before writing anything.
- Find the test seam. Locate the existing test suite and how it's run (from the manifest/CI). Match its framework, file layout, and naming — don't introduce a new test setup.
- Write the smallest failing test. One assertion that encodes the correct behavior (Y). Run it and confirm it fails — and fails for the stated reason, not a setup error. A test that errors on import isn't a repro.
- Fix the cause, not the symptom. Change the code until the new test passes. Don't special-case the test's input; fix the underlying logic so sibling cases are covered too.
- Prove it. Run the new test (green) and the full suite (still green — no regressions). Report what the test asserts so the user can see exactly what was broken.
Guardrails
- The fix should flip the new test red→green and break nothing else. If other tests change, explain why.
- Don't weaken or delete an assertion to make it pass.
- If the bug can't be reproduced in a test, say so and explain what's missing instead of patching blind.
