A decision log is only worth what you can find in it

Somewhere in your team's notes is a decision that was recorded properly. Someone wrote down what was chosen, and why, and when. A genuinely good entry.

Two months later, when the question comes up, that entry will not be found. Not because it was written badly — because finding it requires already knowing which meeting it was taken in, and that is exactly the fact nobody has.

We put real care into writing decisions down, then treat the job as finished when the words hit the page. But writing is not what a decision log is for. Retrieval is. A decision record is a write-optimised artefact used at read time, and that mismatch is where it quietly fails.

A record you can't reach costs the same as one you never wrote

Plus the time it took to write it. That arithmetic doesn't improve because the entry was thorough.

It's an uncomfortable claim, because effort feels like it ought to count for something. Here it doesn't. The log has exactly one job and that job happens at read time; an entry that fails then has failed, whatever its quality on the page.

So don't audit how your entries are written. Pick a decision from three months ago that you personally weren't part of, and time yourself finding out why it was made. That number is what the log is worth.

People don't look up the decision. They look up the constraint

Try it on yourself: name the title of a decision your team relies on every week.

Most people can't — and they don't need to, because the title isn't the handle memory keeps hold of. What survives is the reason, the sharp edge of the thing:

• "the one where we found out about the rate limit"
• "the thing about latency under load"
• "wasn't there something legal said about EU data?"

Every one of those is a phrase from the reasoning, not the title. Which makes the reasoning not commentary attached to the decision, but the index. If a search only matches decision headlines, the log is unsearchable in exactly the way people search.

That's the shape retrieval has to take: a query against why, returning what — with the date and the source meeting attached, so the answer arrives with its provenance instead of as a floating assertion. In Scripta every decision is recorded with its reasoning and its date, attached to the meeting that produced it. That is the raw material retrieval runs on, and it is the reason the next paragraph is a writing rule rather than a tooling one.

The corollary is a writing rule, and a better one than "write good reasoning": write the reasoning in the words the constraint will be remembered by. "Improves scalability" is true and unfindable. "The synchronous path added latency we couldn't shed under load" contains the terms a future colleague will actually type.

Filing by subject is right, and not sufficient

This blog argued a few days ago that a decision should be addressable on its own terms — its own entry, its own title, findable by subject rather than by the event that produced it. That's correct, and this post is the amendment to it: a title only helps a reader who remembers the title.

Filing under "billing" works when the reader knows they're looking for billing. Often they aren't carrying anything that tidy — they're carrying the objection, the constraint, the thing that made the obvious option impossible. Subject-addressability serves the reader who already knows roughly what they want. The reasoning serves the one who doesn't, which on a decision two months old is most of them.

Both, then: filed so it can be browsed, and written so it can be found by the part anyone actually retained.

What a retrievable log changes about the next decision

Not relitigating settled questions is the obvious benefit, and the smaller half.

The larger one: when the last decision is one search away, the next decision starts from a better place. You can see what was tried, which constraint bit, and what the team believed at the time — and disagree with it deliberately rather than accidentally. A reversal made in full knowledge of the original reasoning is a good outcome. A reversal made because nobody could find the original is churn wearing the costume of progress.

That's also the honest case for recording the reasoning behind a call that later proves wrong. In hindsight it reads like a record of a mistake. It's actually the most instructive entry in the log — the one that names which constraint the team misjudged, which is the thing you'd most like to know before misjudging it again.

Capture it where it happens, find it without knowing where that was

None of this argues for a heavier process. Decision logs decay when they're maintained as a separate discipline — a document somebody owns, updates, and eventually stops updating.

The cheapest moment to record a decision is right after it's made, while the reasoning is still in the room and costs a sentence. Capture it there, in the meeting that produced it. Then make sure nobody needs to know which meeting that was.

Better decisions start with remembering the last ones. Remembering, in practice, means finding.