Separate facts from hypotheses

The fastest way to waste a debugging session is to treat a guess as a conclusion. A hypothesis is useful only when a test can make it less likely. Do not turn the first plausible story into a fact.

Facts are things you observed: a status code, a log line, an error message you can paste. Hypotheses are stories that would explain the facts. Keep them physically apart, in writing, so your brain cannot quietly promote one to the other.

Create two columns:

facts:
- POST /login returns 500
- response request ID is r-42
- server log r-42 says connection refused

hypotheses:
- database process stopped
- database address is wrong
- firewall rejects the connection

Notice what the facts already rule out. “connection refused” means the request reached the server, and the server tried to open a connection somewhere. The frontend is innocent. That is why writing facts down pays off: each one prunes the search space before you touch anything.

Test to disprove

Choose one cheap test for each hypothesis. For “database process stopped”, check the process list on the database host. Ten seconds. For “database address is wrong”, print the host and port the app actually resolved. Record the result before changing configuration.

The discipline matters more than the order: run the test, write down what happened, cross the hypothesis out or keep it. A crossed-out hypothesis is progress even though nothing is fixed yet.

Say it out loud

Explaining the two columns to a colleague — or to nobody, which is rubber duck debugging — forces you to state each assumption explicitly. Halfway through the sentence “the app connects to the database on port 5432…” you go check the config and it says 5433. The duck did nothing. You did, by turning a silent assumption into a checkable claim.

Avoid making several fixes at once. If you restart the database, correct the address, and open the firewall in one step, the system may recover — and you lose the evidence that identifies the cause. Next time it happens, you start from zero.