| name | debug-first |
| description | Before fixing a bug: reproduce it, confirm root cause, write a failing test first. |
Debug-first
Run this whenever asked to fix a bug, investigate unexpected behavior, or explain
"why is X happening." Do not jump straight to a plausible-looking fix.
Sequence (do not skip steps)
- Reproduce the bug first. If you can't reproduce it, say so explicitly and ask for
more detail (exact steps, input, environment) rather than guessing at a fix for
something you haven't confirmed.
- Once reproduced, write a failing test that captures the bug. If the codebase has no
test infrastructure for this area, at minimum write a minimal reproduction script
and show its output before touching the fix.
- State the root cause in one or two sentences before writing any fix. If you're not
sure it's the root cause vs. a symptom, say that uncertainty out loud rather than
fixing the symptom and reporting success.
- Write the fix.
- Run the failing test again and confirm it now passes. Paste the actual output.
- Run the broader test suite (not just the new test) to check for regressions.
Edge cases
- If the bug is intermittent/flaky and you can't reliably reproduce it: say so, describe
what you tried, and propose instrumentation (logging, assertions) rather than a blind
fix. Do not claim a fix resolved an intermittent bug without a way to verify it did.
- If reproducing requires an external dependency you don't have access to (a real
webhook payload, a specific API response, a production dataset shape): ask for a
sample/mock rather than fabricating one that might not match reality.
- If the "bug" turns out to be expected behavior or a misunderstanding of the spec: say
that plainly instead of changing code to match an incorrect assumption.
Reporting format
- Reproduction: how, and what you saw
- Root cause: one or two sentences
- Test added: path + the failing-then-passing output
- Full suite result after the fix
- Anything you couldn't verify, named explicitly
