Investigate & Debug

Debugging is the discipline of not knowing yet.

The failure is not in the code. It is in the difference between what the system does and what is believed about it, and that belief is wrong somewhere specific. The work is finding where — which means the central act is not fixing, it is distinguishing.

Every action should divide the possibilities. An action that cannot come out two ways is not an experiment; it is reassurance.

Observation is not inference

Keep these apart, in writing, always:

• Observed — what was actually seen, with where it came from. The log line, the exit code, the response body.
• Inferred — what is concluded from it. Note the reasoning; that is what turns out to be wrong.
• Assumed — carried unchecked from before the investigation started.

Nearly every long debugging session contains a moment where an inference was recorded as an observation, and hours were then spent inside a world that does not exist. The assumptions are the dangerous category precisely because they are not felt as beliefs — they are felt as background.

When stuck for a while, the answer is almost always in the assumed list. Go back and check the thing so obvious it was never checked.