Most of my worst debugging days share a shape. I had a theory early, the theory was good, and the theory was wrong.

Why theories beat evidence

A theory is satisfying. It explains things. It gives you something to do. Evidence is a wall of text with timestamps.

So you reach for the theory. And then — this is the dangerous part — you start gathering evidence that tests the theory rather than evidence that describes the failure. You reproduce it locally. You write a small script. You confirm your idea works the way you thought. None of that tells you whether it's what actually happened in production, but it feels exactly like progress.

I lost two days to this recently. My local reproduction was real. The behaviour I found was real. It just wasn't the thing that was breaking the build.

What reading first looks like

Open the actual failing run. Not a similar one. Not a local one. That one.

Then, before forming any opinion:

• What's the first error, by timestamp? Not the loudest — the first.
• How many distinct failures are there, and do they share a message?
• What passed? A run with 164 passing and 9 failing is a different animal from one with 0 passing.
• Does the failure count change between runs? Stable means deterministic.

That's maybe fifteen minutes. In my experience it either hands you the answer or it rules out most of what you were about to go and try.

The tell

Here's the signal I now watch for in myself: if I'm explaining why the logs would show my theory, rather than pointing at a line where they do, I have left debugging and started arguing.

The log doesn't care about my theory. That's the whole value of it.