Systematic Debugging

For bugs that survive the first obvious fix. The core discipline: find the root cause before writing any fix. A fix without a root cause is a guess, and guesses that "work" hide the real bug. Part of the dev-* development-cycle skill set (see dev-cycle).

Phase 1 — Reproduce and Localize (always)

1. Build a feedback loop first — this gate IS the skill. One command that is red now, deterministic, fast, and runnable without a human — best is a failing test; otherwise a curl against the endpoint, a CLI run diffed against expected output, a throwaway harness script, or a git bisect run wrapper. Run it once and watch it fail before anything else. No red-capable command → no fixing — gather more data instead (logs, inputs, versions). For flaky bugs, don't chase a clean repro — raise the reproduction rate until the loop is usable: run it 100× in a loop, parallelize, inject sleeps at suspected races.
2. Read the actual error. Full stack trace, exact message, line numbers — not a paraphrase.
3. Recent changes first: git log --oneline -20 on the touched files; if the bug is a regression, git bisect run <failing-command> finds the exact commit mechanically — prefer it over reading diffs when there are more than a handful of commits.
4. State the best evidence-backed, falsifiable hypothesis and test it. List alternatives only when they change the next experiment; do not invent a quota of hypotheses. Each in the form "if X is the cause, changing Y will make the bug disappear" — state the hypothesis briefly before testing. Verify with evidence (a log line, an assertion, a minimized input) before changing any code.
5. Tag every debug log with one token ([DBG-4f2a]) so cleanup after the hunt is a single grep — never log everything and grep the noise.
6. After 2 failed hypotheses, stop guessing and move to Phase 2 — the bug is in your model of the system, not in the place you're looking.

Phase 2 — Interactive Debugger (hard cases)

When print-debugging stalls — state mutates unexpectedly, timing matters, the failure point is far from the cause — set the user up with a real debugger at the suspect location. Generate the config for their environment, don't just describe it.

What to generate