| name | debug |
| description | Diagnose a bug systematically - reproduce, isolate, find root cause, then fix - instead of guessing at changes. Use when something is broken, failing, or behaving unexpectedly. |
debug
Find the root cause before changing code. A fix without a confirmed cause is a guess.
Steps
- Reproduce. Get a reliable, minimal reproduction. Capture the exact command,
input, and the full error / stack trace. If you cannot reproduce it, gather the
conditions until you can - do not fix blind.
- Read the evidence. Read the actual error and the relevant code path top to
bottom. The stack trace usually names the file and line; start there.
- Form one hypothesis about the cause and state it explicitly.
- Test the hypothesis with the cheapest probe: a targeted log/print, a unit
test that isolates the suspect, a debugger, or
git bisect for a regression.
Confirm or reject before moving on.
- Fix the cause, not the symptom. Address why it happened, not just the
surface error. If you only have a workaround, label it as such.
- Verify. Re-run the reproduction: it now passes. Run the surrounding tests
to confirm no regression. Add a test that would have caught this bug.
Rules
- Change one thing at a time; revert probes that did not pan out.
- Quote the real error text and the file:line you are reasoning about.
- State your confidence in the root cause; if uncertain, say what would confirm it.
- Resist shotgun edits - if you are changing many things hoping one works, stop
and go back to step 1.
- Leave the codebase clean: remove temporary logging before finishing.
