Debug
Reach for Debug the moment a fix did not work and you feel the urge to try it again with slightly different inputs.
- The second attempt at a fix just failed.
- You are about to type "let me just try this".
- You have restarted, rebuilt, or re-run the same thing more than twice without writing down what each run proved.
- You are about to report "should be fixed now".
The circuit breaker is not optional. Three failed hypotheses means stop, write, re-plan.
The most expensive habit in technical work is trying the same approach a fourth time with slightly different inputs. It feels like persistence. It is almost always a sign the diagnosis is wrong, not the execution: something you believe about the system is false, and every retry tests the execution instead of the belief.
Two Rules
- No fix without a written hypothesis. A stated guess about what is wrong and the evidence that would prove it, written before anything changes. "I'll just try this" is the excuse this rule refuses, because one untracked change turns into ten and then nobody knows which one mattered.
- The circuit breaker. After three failed hypotheses, the session stops, writes a handoff, and re-plans. No fourth guess. Listing three attempts makes it impossible not to notice they shared an assumption.
The Handoff
A short file, and its shape is the discipline:
- Problem. One line.
- Hypotheses. Each marked eliminated or still open, with the evidence that eliminated it.
- Current belief. What we now think is happening, usually not what we believed an hour ago.
- Next action. A concrete step, like "add logging at this line" or "diff these two outputs". Never a direction like "keep investigating".
Come back tomorrow, or hand it to someone else, and the dead ends are on the page so nobody walks them twice.
How A Fix Gets Reported
| Required | Not Acceptable |
|---|---|
| Root cause at a file and line | "Should be fixed now" |
| Fix at a file and line | "Refresh and let me know" |
| Evidence from this session, in the same message | "It worked earlier" |
Either the proof is in the message, or the message says which step still is not proven.
The Rejected Column
| Excuse | What To Do Instead |
|---|---|
| "I'll just try this" | Write the hypothesis first. |
| "Patch the symptom now, root cause later" | Find the root cause. A symptom patch plants a new bug elsewhere. |
| "Stack a second fix on the first" | Revert and re-hypothesize. Two wrong fixes can cancel out on Tuesdays. |
| "One more run" | If it is attempt four, stop and write the handoff. |
Where It Sits In The Loop
Debug runs while you build. Its report should name the root cause and the fix at a file and line. Verify then checks that report, because a root cause with no test behind it is still only a tier-one claim.