A Debugging Journal You Write During the Hunt, Not After

2026-09-15 · Yesterself

Every working programmer has had this moment. A bug lands, something about it feels familiar, and you know — not vaguely, but with real conviction — that you have solved this before. You cannot remember the cause. You remember the shape of the afternoon it cost you. So you spend the afternoon again.

A debugging journal is the cheap fix for that. The catch is that most people write one at the wrong time, and a note written at the wrong time is nearly worthless.

Why writing it up afterward fails

When the bug is dead, you write something like: "Connection pool was exhausted because failed retries never released their connection." True, tidy, and almost no help to anyone, including you.

It is the answer with the work deleted. What you actually needed six months later was the middle: the four things it looked like, the two you eliminated in a minute and the one that cost three hours. Those are the parts that make the next bug recognizable, and they are the first things to evaporate.

There is a second problem. Once you know the cause, memory quietly rewrites the hunt so that every step leads neatly to it. The forty minutes you spent staring at the wrong service disappear. The false lead that looked completely convincing at 2 p.m. gets edited out — and the false lead is exactly what will look convincing again next time.

So write during. Not a novel. A form you fill in as you go.

The five fields

Open the note before the second thing you try. The first thing you try is a reflex; the second means it is a real hunt.

1. Symptom, in the words you would search for

Paste the exact error text, not a paraphrase. Then add the observable behavior in plain language: what you saw, where, when it started, how often, and what makes it happen again. If you cannot reproduce it yet, write "not reproducible yet" and note what you have tried.

Write this the way a stranger would type it into a search box. Future you will be a stranger.

2. Hypotheses, written before you test them

This is the field that changes how you debug, not just how you remember. Before you run the next command, write the sentence: "I think it is X, because Y, and if I am right then Z will be true."

Committing to a prediction has an effect nothing else does. It makes it obvious when you are shotgunning — when you have run six things in a row without expecting anything in particular from any of them. And it turns each test into a fact rather than a mood.

3. What you ruled out, and how

One line each. Not just "not the database" but "not the database — query log shows the same statement at 8 ms during the incident window."

This is the field that pays. Six months on, a bug that rhymes with this one arrives, and the ruled-out list saves you from re-walking every dead end. It also protects you inside the same hunt, at hour four, when you start to doubt yourself and are tempted to check something you already checked.

Include the confidence. "Ruled out, definitively" and "probably not, only checked one instance" are different facts, and by next week you will not remember which one you had.

4. The cause

When you find it, write two things: the mechanism, and the reason it presented as that symptom. The second half is the one people skip and the one that makes the note findable, because the gap between the cause and the symptom is precisely what confused you.

Also record what misled you and why the wrong explanation looked right. That is the transferable lesson.

5. The fix, and the fingerprint

The fix is one line, with a link to the change rather than a copy of it. Then a fingerprint line: every string that would show up in logs, dashboards, or a search box when this happens again, including the aliases. "504" and "gateway timeout" and "upstream connect error" are the same event with three vocabularies, and you will not remember which one you saw.

The whole form should fit on one screen. If it takes longer than a few minutes, it will not survive contact with a bad week, and a practice that only runs on good weeks records the easy bugs and misses the expensive ones.

Making a year of them findable

A pile of notes you cannot search is a diary, not a tool. Retrieval is half the practice and it gets almost none of the attention.

One note per bug, in one place. Flat directory of plain text files, or one long file per quarter — either works. What does not work is scattering the record across ticket comments, a chat thread, a pull request description, and your head. Four places you cannot search at once is zero places.

Name and index by symptom, not by cause. The natural instinct after solving it is to file the note under the answer: "stale-clock-skew.md". But you will never search for that, because when the bug returns you do not yet know it is clock skew. You know that a webhook came back as a duplicate. File it under the symptom, and let the cause live in the body.

Write the alias line deliberately. Two minutes spent listing alternate phrasings — the error code, the human description, the name of the component, the name your team actually uses for it, the customer-facing wording — is what turns a keyword search into a hit. This is the single highest-return habit in the whole practice.

Link out, do not copy in. Commit hashes, ticket IDs, dashboard URLs. Assume the dashboard link will rot and the reasoning will not, and put the reasoning in the note.

When a bug rhymes, edit the old note too. Add one line to the earlier entry: "happened again, different service, same assumption about ordering." A class of bug only becomes visible once the notes point at each other. This is where the practice stops being memory and starts being knowledge.

Skim quarterly. Twenty minutes reading your own titles. You are not looking for individual bugs; you are looking for the sentence "three of these were the same wrong assumption about time zones." That sentence is the real product of the whole exercise, and no single note contains it.

What to leave out

Keep customer data, credentials, tokens, and personal information out of a personal log, especially one that syncs somewhere. Write "the token was expired," never the token.

Keep it out of anything that functions as a performance record, too. A note that might be read as evidence against you will quietly become a note about how competent you looked, and that version is useless. The whole value depends on being able to write "I spent two hours on completely the wrong service because I misread the hostname."

And do not wait for tidiness. A rough note written at hour two beats a polished one written never.

A note on where these live

Some people keep the log in the repository, which is right for team-visible knowledge. Some keep a private one alongside it, because the honest version includes what you were confused about, and that is a different kind of writing.

If the private half is where yours lives, it helps to use something that hands old entries back to you rather than only storing them. Yesterself delivers one letter from your own past writing each morning, and any sentence can be postmarked to a future date — which is a natural fit for "check whether the timeout fix actually held" arriving sixty days from now, when you have entirely forgotten you wondered.

The economics of this practice are strange, and worth saying plainly. Most notes are never read again. Six minutes each, quietly wasted. Then one Tuesday a bug arrives for the third time, you search four words, and you get back an afternoon — along with the four dead ends you would otherwise have walked down a third time.

Common questions

What is a debugging journal?

It is a short note per bug, written while you are still hunting rather than after the fix. It records the symptom in the words you would search for, the hypotheses you formed, what you ruled out and how, and the cause you finally found.

How is it different from a postmortem or a ticket comment?

A postmortem records the destination. A debugging journal records the wrong turns, which is the part you need when a similar bug shows up months later. Ticket comments are written for other people and get scattered across systems you cannot search as one place.

What do I write when I am still stuck and have no answer yet?

That is the best time to write. Note the symptom exactly, the hypothesis you are about to test, and the result. A note that ends in "still unknown, ruled out these four things" is more useful later than no note at all.

How do I find an old note a year later?

Index by symptom words, not cause words, because future you searches with what they can see. Add a line of alternate phrasings and exact error strings at the top of each note so a keyword search hits it.

Is this worth doing if I work alone?

Especially then. With no team to ask, your own archive is the only institutional memory available, and a solo project usually has longer gaps between encounters with the same class of bug.