systematic-debugging

Systematic Debugging

Do not begin with a plausible patch. Begin with a verified symptom and an explanation that accounts for the evidence.

1. Reproduce

Capture the smallest reliable reproduction:

• exact command, input, environment, and observed output;
• whether the failure is deterministic;
• the last known good version or condition when available;
• the component boundary where expected behavior first diverges.

If the reported problem cannot be reproduced, gather logs or instrumentation. Do not manufacture certainty.

2. Establish the causal chain

Trace data and control flow backward from the bad observation:

1. What value or state is wrong?
2. Which producer created it?
3. What assumptions did that producer make?
4. Which upstream event violated those assumptions?
5. Why did existing validation or tests not catch it?

For distributed, asynchronous, or native boundaries, record timestamps, identifiers, generations, ownership, and cleanup, not only error strings.

3. Form competing hypotheses

List the few explanations consistent with the evidence. Rank them by how much they explain, not by convenience. Design the smallest discriminating experiment for the leading hypotheses.

Change one variable at a time. Instrument before rewriting. A failed hypothesis is useful evidence; remove its instrumentation when finished.

4. Confirm root cause

A root-cause explanation must predict:

• the original failure;
• at least one nearby edge case;
• why the obvious or prior fix was insufficient;
• the location where a durable invariant can prevent recurrence.

If the same attempted fix fails twice, stop cycling. Re-examine the model, consult one bounded diagnostician, or revise the design.

5. Fix through TDD

Load test-driven-development:

• encode the smallest regression proof;
• observe RED on the defective behavior;
• implement the invariant-level fix;
• observe GREEN;
• perform a revert or mutation check;
• run affected tests and any concurrency/resource cleanup checks.