Write Down Why, Not Just What

Most projects I've joined had some record of their decisions. A wiki page. An ADR folder. A pinned message that said "we're using Postgres". These records answer one question well: what did we choose?

They almost never answer the questions people actually ask six months later:

• Why did we choose it?
• What else did we consider, and why did those lose?
• What does this choice cost us?
• What haven't we decided yet?

This summer I wrote a long document for a governance runtime I've been building that tries to answer all four. I called it a decision dossier. It turned out to be one of the most useful things in the repo, for people and for the agents that help me build it.

The difference between a log and a dossier#

I keep both, and they do different jobs.

The decision log is short and numbered. Each entry is a few lines: the decision, the date, a pointer to where it's enforced. It's the index. It's what you grep.

The dossier is the reasoning layer above it. It's a single narrative that explains why the product is shaped the way it is. Every claim in it traces back to a numbered entry in the log, so the two can't quietly disagree.

If the log is the table of contents, the dossier is the book.

One rhythm for every decision#

The most important choice I made was to give every section the same shape. A reader can skim any decision in the same way, and a writer can't skip the uncomfortable parts.

Every decision gets six parts:

1. The stakes. The fork in the road, and what a wrong turn costs.
2. The decision. What we chose, in one or two sentences.
3. Why. The reasoning, including the alternatives we rejected and why they lost.
4. How it works. How the decision shows up in the product today, at the level of real contracts and code paths.
5. The trade-off. What this costs us, stated plainly.
6. Traceability. The numbered log entries that bind it.

Two of these do most of the work.

Rejected alternatives stop the same debate from happening again. When someone new asks "why not just use X?", the answer is already written, with the reasoning, not just the conclusion. Often the reasoning is still sound. Sometimes it isn't anymore, and then you know exactly which assumption changed.

The trade-off keeps the document honest. Every real decision costs something. If a section can't name its cost, it's usually a sign the decision wasn't really made. It was assumed.

An example#

Here's the shape, compressed, for one decision in the governance runtime: whether customers' systems should call a hosted decision service or embed the decision logic as a library.

• Stakes: an embedded library is fast and private. A hosted service adds a network hop. But the product's value is a verifiable record of every decision, and where that record gets written decides whether it can be trusted.
• Decision: decisions go through a hosted, standards-based HTTP API. Any local evaluation is advisory only.
• Why: the evidence has to be written in the decision path. If evaluation ran only inside the customer's process, the record would live on their side, where nobody else could trust it. Alternatives rejected: a proprietary API, which gives up the reach of a public standard, and an event queue, which breaks the "answer before you act" contract.
• Trade-off: customers take on latency and availability risk. Our uptime becomes part of the trust story.

Four short paragraphs. Anyone who reads them understands why the product is a service and not a package, and what we gave up to get there.

Name the tensions you're holding#

Beyond individual decisions, the dossier has a section I didn't expect to value as much as I do: the tensions we're holding on purpose.

These aren't problems to solve once. They're trade-offs to keep in view so they never get resolved by accident. A few kinds come up in almost every product:

• Speed vs. care. Making something frictionless can erode the judgment it was meant to support.
• Visibility vs. surveillance. Showing leaders what's happening shouldn't turn into watching people.
• Now vs. later. The shape that wins the first customers may not fit the customers you want in two years.

Writing these down means that when a feature request pushes on one of them, the conversation starts from a shared understanding instead of a fresh argument.

Name what you haven't decided#

The last section is a table of open questions. Each one has:

• The area it affects
• The question, stated plainly
• Why it's still open

Pricing. Where a future component should live. How to tell an agent's action from a person's in the data. These are real gaps, and listing them is a form of honesty. It tells a new engineer where not to assume an answer. It tells me which decisions are blocking which work.

It also stops a quiet failure: someone makes an open decision implicitly, in code, because nobody said it was open.

The bug the dossier found#

Here's the part that sold me.

While writing the section on how rules get approved, I described a two-person rule: the person who submits a rule change can't also be the one who approves it. Every document in the repo said the same thing. The product spec said it. The design notes said it.

To write the "how it works" part, I went to find the line of code that enforced it.

There wasn't one. The interface hid the approve button from the submitter, but the server didn't check. Anyone who called the action directly could approve their own change.

The fix was small: the server now compares the approver to the submitter and rejects a match, no matter what the UI shows. It got its own numbered entry in the log. But it only surfaced because the dossier's format forced me to connect a claim to a code path. A document that only says what you chose would never have caught it.

That's become a rule for me: if a decision matters, the dossier has to point to where it's enforced. If you can't find the enforcement, you've found a bug or a myth.

Why this matters more with agents#

I build a lot of software with AI agents now, and this kind of document has become a core part of how I give them context.

An agent reading a codebase can see what the code does. It can't see why. Without the why, it makes reasonable changes that undo deliberate trade-offs. It "simplifies" a check that was redundant on purpose. It adds a client cache to a product that decided not to have one by default.

A dossier changes that. When an agent's plan conflicts with a written decision, it can see the conflict and the reasoning, and either follow the decision or flag that the reasoning no longer holds. That's the same thing I'd want from a new engineer.

It also connects to how I think about agent context more broadly, which I wrote about in Skills, Standards and Context.

How to start one#

You don't need to write the whole thing at once. Here's how I'd start on an existing project:

1. List the ten decisions you'd hate to see reversed by accident. Those are your first sections.
2. Write each in the six-part rhythm. Keep each to a page or less.
3. Find the enforcement for each. A test, a server check, a lint rule or a gate in CI. If it's missing, note it.
4. Add a short tensions section. Three to five, in plain language.
5. Add an open-questions table. Be honest about it.
6. Keep a numbered log underneath. One line per decision, linked from the dossier.

Then make it a habit: when a new binding decision lands, it gets a log entry and a dossier section in the same change.

The takeaway#

A list of decisions tells people what to do. A dossier tells them how to think about the product when a new situation comes up. Writing down the stakes, the rejected options, the cost and the open questions takes a few extra hours. It saves weeks of repeated debate, gives agents the context they need, and occasionally finds the gap between what everyone believes and what the code actually does.