Systematic Debugging

Debug by finding the cause, not by trying fixes. One loop: reproduce → evidence → hypothesis → minimal fix. Skip a phase only when you can state why its output is already known.

Phase 1 — Reproduce

• Get a failing reproduction before changing anything: the exact command or interaction, its full output, and the exit status.
• Shrink it to the smallest input and scope that still fails.
• If the failure is intermittent, record the observed frequency and conditions instead of pretending it is deterministic.
• No reproduction yet means the work is still investigation, not fixing.

Phase 2 — Gather Evidence

• Read the actual error, stack trace, and logs before forming opinions; quote the relevant lines, not a paraphrase.
• Compare against a known-working state: recent diffs, a passing sibling case, another environment.
• Evidence stays boundary-safe: never dump environment variables, credentials, tokens, or full config files into output or logs. For sensitive values, log names, lengths, or shapes — not contents.
• Locate the failure boundary: the last point where state is known good and the first point where it is wrong.

Phase 3 — One Hypothesis, Tested Minimally