Decision Records Capture the Why, Including the Ones You Reverse

The most expensive thing to lose on a project isn’t the code. It’s the reasoning. Six months later the code tells you exactly what was decided and absolutely nothing about why, what alternatives were on the table, or what constraint made the obvious choice the wrong one. So you re-litigate a settled question, or worse, you “fix” something that was deliberate. I’ve started keeping a lightweight decision log on work that matters, and the habit pays for itself the first time someone — often me — asks “wait, why did we do it this way?”

Code is the answer; the decision log is the working

A codebase is a stack of answers with the working erased. That’s fine for what the system does, but most of the genuinely hard calls on a project aren’t visible in the code at all — they’re the tradeoffs you weighed, the option you almost took, the thing you ruled out for a reason that isn’t written anywhere. When that reasoning lives only in your head, it has a half-life measured in weeks.

Code records the decision. It never records the alternatives you rejected or the reason you rejected them — which is exactly the part the next person needs.

A decision record is the cheap fix: a short note per meaningful decision, in the repo, capturing the context at the time, the options considered, what you chose, and why. Architecture Decision Records (ADRs) are the formal name, but it doesn’t need ceremony — a few sentences of “here’s the situation, here’s what we picked and why” is most of the value. The point is to write down the working, not just the answer.

Write it at decision time, not at documentation time

The reasoning is only accurate while it’s fresh. Reconstructed after the fact, it becomes a tidy story that smooths over the real messiness — the dead end you went down, the constraint you didn’t fully understand yet, the thing you were unsure about. Those are the most useful parts to preserve, and they’re the first to evaporate.

So I write the record when the decision is made, with the uncertainty intact. “We’re choosing X; we’re not fully sure about Y; if Z turns out to be true we’d reconsider” is worth ten times a confident retroactive summary, because it tells the next person which assumptions to recheck. A decision log is a journal, not a press release — capture it in the moment, warts and all.

The most valuable record is the one you reverse

Here’s the part that surprised me into actually believing in this. The single most useful entry I’ve written was a decision reversed by a later decision — and both were correct.

Early on, I’d built a new capability as a separate, parallel thing alongside the existing one, specifically so it had zero blast radius and could be removed with a single clean undo. That was the right call for that moment: I was experimenting against something fragile and wanted a trivial rollback. Later, the constraints changed — it turned out the consumers were external and couldn’t switch to the new thing on any useful timeline — so I reversed course and modified the original in place instead, accepting more risk because it was now the only approach that was invisible to those consumers.

A decision you later reverse isn’t a mistake to hide. It’s two correct calls under two different sets of constraints, and the record of why each was right at the time is the most instructive thing in the whole log.

Without the record, that reversal looks like flip-flopping or sloppiness. With it, it’s a clear story: here’s why we kept it separate, here’s the constraint we learned, here’s why that made us reverse. Anyone reading later understands both the original caution and the reason it no longer applied — which is exactly the judgment you want to transfer. It’s the same “work the constraint you actually have” instinct I wrote about in deploying with the access you have; the decision log is where that reasoning gets preserved.

It keeps parallel work from colliding

A practical, less philosophical benefit: on anything touched by more than one person (or more than one session, if you work with AI agents that don’t remember last week), the decision log is how work doesn’t collide. “We deliberately did read-only discovery first and applied no changes” is a decision that lets the next person pick up an individual item without wondering whether they’re stepping on an in-flight change. The log encodes not just what’s done but what’s intentionally not done yet, which is often the more dangerous thing to guess about.

Keep it lightweight or it won’t happen

The failure mode of decision records is the same as all documentation: if it’s heavy, nobody writes it. So mine are deliberately small — a numbered list, a few sentences each, living next to the code. No template to fill out, no approval flow, no separate system to log into. The bar is “would future-me thank me for this sentence,” and if the answer is yes it goes in. This is documentation as infrastructure at its most minimal: not a manual, just a running record of why the system is the way it is.

The whole practice is one cheap habit: when you make a non-obvious call, write down why, including what you ruled out — and when you later reverse it, write down what changed rather than quietly editing history. The code will always tell the next person what you did. Only the decision log tells them whether to trust it or change it. If you keep a decision log in a form that’s actually stuck, I’d genuinely like to hear how you do it.