debug

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

1. 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.
2. 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.
3. Form one hypothesis about the cause and state it explicitly.
4. 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.
5. 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.
6. 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.