I rewrote the same translation-routing decision three times before I started writing decisions down.
The pattern was always the same. A question came up — should we machine-translate the SEO articles or human-translate them? — I thought about it, made the call, shipped. Two months later, the question came up again. I'd forgotten the original argument; I had to re-derive it from scratch. Half the time I made the same call. Half the time I made a different one, then realized later that I'd already decided this once and reverted.
The cost of an unwritten decision isn't the time you spent making it. It's the time future-you spends re-litigating it, plus the occasional inconsistency that ships because past-you and future-you didn't quite agree this time. The decision unread is the decision relitigated.
Write the decision down. Not later. Now.
The candidates for where to write decisions were the usual suspects. A Notion page. A #decisions Slack channel. A meeting recording. Each one optimizes the wrong thing — Notion is in a different login than the code, Slack is searchable for forty days, recordings are unsearchable. The thing that matters is that the decision is readable in the same context as the code it shapes. That context is the repo.
The transferable why: write decisions in the medium future-you will be reading. If future-you reads code, write decisions next to the code. If future-you reads emails, write decisions in emails. If future-you reads Notion, write decisions in Notion — but expect them to drift the day your code changes, because the change history of the documentation has nothing to do with the change history of the system it documents.
Locked 2026-05-08 · decisions/ in the repo · plain markdown
The second decision was about the format of the decision file itself.
A decision that lives in a file nobody reads is a decision that gets violated within a week. The first version of decisions/ had no frontmatter, no broadcast, no notification — just a file. The agents never read it. I never read it. It rotted alongside the codebase it was supposed to govern.
The fix was to make every decision a broadcast, not a document. Every file starts with a frontmatter block that names the decision, the agents it applies to, and the channels it should broadcast to:
id: 2026-05-08-torque-converters-common-values
applies-to: [bob, lace]
broadcast: [slack-engineering, weekly-digest, email-daniel]
The broadcaster Worker watches the decisions/ directory. New file lands → broadcast fans out. Slack channels named in the frontmatter get a notification. The events table gets a row. The applies-to agents get the decision injected into their next session's context. The decision moves from "filed in a folder" to "delivered to the people and bots who need it" without me typing a second character after writing the file.
The transferable why: a decision that doesn't notify anyone is a decision waiting to be ignored. Make the notification mechanical — even a single-line cron that fans new files to Slack is enough — and the social cost of catching a violation drops to zero. The decision starts behaving like a policy instead of a wish.
Locked 2026-05-08 · decision-as-event · enforced by agent-os-broadcaster
The third decision sounds small and turned out to load-bear.
When the count crossed twenty decision files, I was tempted to move them to Notion. Notion has search. Notion has rich text. Notion has comments and threading and a UI somebody other than a developer can use. Markdown files in a repo have none of that. The case for migrating was real.
I almost did it. The thing that stopped me was the cancellation paragraph I'd written for /membership a week earlier — "Cancel and the microapps you used are still there. Nothing is held hostage." A repo has the same shape. The decisions are next to the code they shape. They share git history with the code. They have git blame. You can't quietly delete an old decision — the deletion is itself a tracked change. Notion has none of those properties, and a system that documents itself in a medium that's softer than itself drifts.
The repo is the source of truth. Everything else mirrors it.
Decisions stay in the repo. The /decisions/ page on this site is a generated index. The Notion-style search is built on top of the repo, not against it. The Slack notifications mirror the repo. The newsletter digest pulls from the repo. Every other view of decisions is a projection of the canonical source — and the canonical source is the one place that shares its change-history with the code it governs.
The transferable why: documentation that lives in a different system than the code is documentation that drifts. The medium has to share the change-history with the thing it's documenting, or the documentation lies the moment the code changes underneath it. Pick the medium for the change-history, not for the UI. The UI is the easy part to add later; the change-history is the hard part to retrofit.
Locked 2026-05-08 · repo-first · decisions/*.md · everything else is a projection
The fourth decision was about the template — whether to have one at all, and how strict to make it.
Templates ossify. Freehand drifts. The version that survives is the version that's just opinionated enough to read consistently across a year of decisions, and just loose enough that no one balks at writing one. I wrote about a dozen decisions freehand, looked at the consistencies that had emerged, and codified the format into decisions/README.md.
Every decision opens with the context — one paragraph on what triggered the decision, what was at stake, what alternatives were live. It states the call in one sentence. It enumerates consequences — the parts of the system that change because of this decision, plus the things that explicitly don't change. Length: 100 to 300 lines. Long enough to record the reasoning; short enough that a future reader will actually read it.
Context. Call. Consequences. In that order.
The template is two paragraphs of guidance plus one example file. Anyone — agent or human — can write a decision in ten minutes. The format is opinionated enough that decisions written months apart read like they came from the same author; loose enough that the writer doesn't have to fight the structure.
The transferable why: templates exist to keep the activation energy low. A template that's two sentences long gets used; a template that's a page long gets bypassed. Pick the shortest possible template that produces consistent output, and accept that consistency is more valuable than completeness. The decisions that get written are infinitely more useful than the decisions that almost got written.
Locked 2026-05-08 · decisions/README.md · context / call / consequences
That's the decision practice. Repo-first, broadcast on write, short template, change-history shared with the code. Browse the live decisions at /decisions/ in the repo.