Writing as a Debugging Tool

There is a moment in a hard bug when more logging makes you less sane. The traces multiply. Everyone has a theory. The room fills with “maybe.” That is when I open a blank page and write as if I were sending a letter to a future teammate who is allowed to be annoyed.

I write what we think happens. I write what we observed. I write the gap in ordinary English. I am not allowed to use the words “race,” “weird,” or “sometimes” without an example. Half the time the gap is the bug: we never actually agreed on the order of events.

Why sentences work

Code will accept an unfinished story. It will compile a contradiction if you put it in two files. Prose is ruder. A paragraph that says “the job starts after the row exists” cannot also say “the row is written by the job” without sounding drunk. That embarrassment is a feature.

I keep these letters. Some of them become postmortems. Some become the first paragraph of a design. A few become essays on this site. The point is not documentation. The point is to make the system hold still long enough to see it.