debugging

Debugging

The Iron Law

NO FIX BEFORE THE CAUSE IS NAMED

A change that makes a symptom disappear without explaining it is a mask, not a fix: the defect stays and the evidence is gone. Naming the cause means saying which line produced the wrong value and why. "It passes now" is not a cause.

The law binds hardest where it feels most skippable — under a deadline, when the fix looks obvious, when someone hands you the patch to apply, and after two attempts have already failed.

Phase 1 — Reproduce

Run the failing thing yourself and read the whole output: the error text, the stack frames, the line numbers. A reported symptom is secondhand; the run is evidence.

Then narrow it. What makes it happen, what makes it stop, and what changed recently (git log, git diff) on the code path it touches.

• Done when you have triggered the failure yourself and can state the exact command, the exact error, and whether it happens every time.

Not reproducible on demand → that is a finding, not a blocker. Open references/intermittent-failures.md when identical runs disagree.

Phase 2 — Locate the origin

Where the error surfaces is rarely where the defect lives. Take the wrong value and walk backward — who passed it here, who computed it there — until you reach the code that first produced it from correct inputs. That producer is the origin.

Open and read the files along that path. A module you never opened has not been ruled out, and "that part is fine" is a claim about the past, not about this run.

Crossing a component boundary (service to service, CI to build to sign) blinds the walk: instrument each boundary, run once, and read where the value stops being right. Both techniques in full: references/finding-the-origin.md.

• Done when you can point at the line that produced the wrong value and say why it produced it.

Phase 3 — Test one hypothesis

Write it as one sentence: "X is the cause, because Y." Then make the smallest change that would tell you whether you are right.