The Decision Journal
A decision written down with the evidence, the alternatives, the reason, the assumptions and when to revisit is a decision that can be re-made on purpose. One that lives only in the code is re-argued every time the code surprises someone.
The situation, the reflex, and why it stalls
Every lesson starts where being stuck starts: someone has a problem, and the first move that comes to mind feels like progress.
How do you record a decision so that, when the requirement changes, the next person can tell whether the decision still holds — without re-fighting it?
Someone new asks why the cart is server-side, and the answer is "I think the founder said something about devices?" The commit says "add cart table". The meeting that decided it was six weeks ago and its reasoning is in three people's memories, differently.
Write a document — or, more commonly, resolve to write one after the next decision, and put the reasoning in the code comment or the commit message where it will be near the code. Both feel like documentation; the second feels like documentation that will actually be read.
The commit message says what changed and not what was traded against what, so it answers "what?" and not "should we still?". A comment says "server-side so it survives devices" and not what would have made the browser cart right.
- The commit message says what changed and not what was traded against what, so it answers "what?" and not "should we still?". A comment says "server-side so it survives devices" and not what would have made the browser cart right.
- The document, when written, is a design document: it argues for the decision and omits the alternatives it beat, so a reader cannot tell whether the argument still holds when the constraint moves.
- Nothing says when to look again. The cart decision was provisional on the founder's guess about device switching; six weeks later the guess has data behind it and no one knows the decision was waiting on it.
- The reasoning survives in memory, which means it survives as a story each person tells slightly differently, and the disagreement about what was decided becomes a second decision.
The move
Precisely enough to apply it to a problem you have never seen — not a slogan.
- Record every decision above the reversible-in-minutes tier as an entry with six parts, none optional: the decision itself in one sentence; the evidence it was made on, including "none"; the alternatives considered, each in a line; why this one — the axis and the requirement that decided it; the assumptions it rests on; and when to revisit — a trigger, a date or a number, with an owner.
- Write it at the moment of deciding, not afterwards. The evidence and the alternatives are freshest then and are the first things memory rewrites; a journal entry written a week later is a justification.
- Keep it where the next change will find it — next to the code, in the repository, searchable by the noun it is about. A journal nobody opens is a diary; the test of the entry is that a stranger reading it can say whether the decision still holds.
- Reopen entries when their triggers fire or their assumptions move, and write the re-decision as a new entry that links the old one. The journal is a history of what was believed and why, not a list of current truths.
One entry, in full
The cart decision as a journal entry. Nothing here is a template to fill mechanically; every line is an answer to a question the next person will ask, and the two lines most often left blank — evidence and revisit — are the ones that make it re-decidable.
1Decision Cart is server-side: one cart table keyed by session,2 with an optional account id. (2026-xx-xx)3 4Evidence Founder: "customers browse on a phone and buy on a laptop".5 No measurement; no customers yet.6 7Alternatives8 - Browser local storage: simpler, no round trip; lost on9 device change or cleared storage; totals computed twice.10 - Separate cache store: fast; a second system to run and11 keep consistent with orders.12 13Why Reliability across devices (per founder) and one place14 to compute totals. Simplicity and performance lose a15 little; cost and security do not move.16 17Assumptions18 - Device switching is common enough to matter.19 - Carts are small (tens of items, not thousands).20 - Abandoned carts are worth being able to see.21 22Revisit At N orders: compare carts started on one device and23 completed on another. Owner: whoever runs the funnel.24 Also if guest checkout changes the session model.The evidence line says "no measurement" in plain sight, and the revisit line has a number and a name. Those two lines are what a design document leaves out and what a re-decision needs.
What each part is for
Each of the six parts answers a question a future reader will ask. The matrix says which question, and what goes wrong when the part is missing — because the shape is easier to keep when you know what each line prevents.
| Part | The future question it answers | Missing, the reader… |
|---|---|---|
| Decision | What exactly did we do? | reconstructs it from the code, and gets the shape but not the intent |
| Evidence | What did we know at the time? | assumes the decision was better-founded than it was — or worse |
| Alternatives | What did this beat, and could that be right now? | proposes the beaten alternative as if it were new, and the meeting happens again |
| Why | Which axis and which requirement decided it? | cannot tell whether a changed requirement changes the decision |
| Assumptions | What would have to be false for this to be wrong? | has no way to notice the decision has quietly stopped holding |
| Revisit | When do we look again, and who? | lets a provisional decision become permanent by silence |
When to write one
Not every decision earns an entry; the tier from the reversibility lesson sets the line. The decision device below is the line, with the cost of each answer — because writing too many entries kills the journal as surely as writing none.
How much of a record does this decision need?
when A rename, a local refactor, a convention that a search-and-replace undoes.
cost Occasionally someone asks "why?" and the commit message has to do; acceptable, because reversing is cheaper than asking.
when A library picked for one module, a default value with a reason.
cost A minute per decision; a journal of one-liners is scannable and rarely wrong.
when Schema, public API shape, where state lives, which provider, the architecture tier.
cost Ten minutes at the worst moment, every time — and an entry honest enough to be used against you; the price of being re-decidable.
when Partition keys, cloud topology, the core data model of a long-lived system.
cost The entry includes what the experiments showed and is the longest thing in the journal; it is also the one most read.
How to do it
Most important first.
- Before the meeting ends, write the six parts on one screen. If "alternatives" is empty, the decision was not a decision; if "evidence" is empty, write "none" and let it be visible.
- Tie "why" to an axis and a requirement with a source: "reliability: survives device change, per founder" — not "it is better" (Trade-Off Thinking).
- Write assumptions as things that could be false, so that someone can notice when they become false (The Assumption Register).
- Give the revisit trigger a number or a date and a name. "When we have order data" is not a trigger; "at N orders, owner: whoever runs the funnel" is (Deciding Under Uncertainty).
- Link the entry from the code it shapes — a comment with the entry's id near the cart table definition — so the journal is found from where the question arises.
Worked on a concrete problem
The move has to produce something. This is what it produced.
- The cart entry. Decision: cart is server-side, one table, keyed by session with an optional account. Evidence: founder's statement that customers browse on a phone and buy on a laptop; no measurement. Alternatives: browser local storage (simpler, no round trip, lost on device change); a separate cache store (fast, a second system to run). Why: reliability across devices, sourced from the founder; one place to compute totals. Assumptions: device switching is common enough to matter; carts are small; abandoned carts are worth seeing. Revisit: at a set number of orders, compare carts started on one device and completed on another; owner named.
- The revisit, later. The funnel shows device switching is rare and abandoned-cart review is used weekly by the founder. New entry, linking the old: decision unchanged, but the reason has moved — the server-side cart now stands on abandoned-cart visibility rather than on device switching. Nothing was rebuilt; the journal recorded that the decision now rests on a different leg, which is the thing memory would have lost.
- The total-storage entry from Trade-Off Dimensions, in the same shape: decision: store the order total at checkout; evidence: the refunds requirement needs "what was paid" to be stable; alternatives: compute from current prices; why: reliability and maintainability — an order is a record; assumptions: no post-checkout price negotiation; revisit: if a subscription or repricing feature is proposed.
How you know it worked
What now exists that did not before, and what question you can now ask.
- A newcomer can answer "why is the cart server-side?" from the repository in under a minute, and the answer includes what would have made the other option right.
- Every entry has an alternative and an evidence line, and some evidence lines say "none".
- Revisit triggers have fired and produced new entries linking old ones; the journal has a history.
- The same decision has not been re-argued in a meeting since it was written.
The questions you can now ask
The field this whole domain exists for. After this lesson, these are the questions to put to an unfamiliar problem.
- ?What was this decided on, what did it beat, and why — and can I find that from where the question came up?
- ?Which assumption in the entry could be false now, and who is watching it?
- ?When is the revisit, and whose name is on it?
- ?If I re-decided today with what the journal shows, would I choose the same — and if the reason has moved, have I written that down?
What can go wrong
- Journal as bureaucracy. Every rename gets an entry, the journal has hundreds, and nobody reads it. The tier that gets an entry is the one from Reversible vs Irreversible Decisions: reversible-with-a-migration and above.
- Entries written to persuade. The alternatives are strawmen and the evidence is selected; the entry reads well and cannot be used to re-decide. The test is whether the strongest alternative is stated well enough that someone could pick it.
- Triggers without owners. The journal is full of "revisit when…" and nothing is ever revisited; the trigger needs a name.
- Edited history. An old entry is updated in place when the reason changes, and the record of what was believed at the time is gone. New entry, link the old one.
- An entry costs minutes at the moment when the decision feels finished and everyone wants to leave; that is the cost, every time, and it is why journals die.
- A journal that is honest about "evidence: none" is a document that can be used against the team by anyone who wants to argue the decision was careless. The honesty is the value, and it is a cost.
- Linking entries from code is a small tax on the code, and the links rot when the code moves; a journal found only by grep is still better than one found by memory.
- "This is an ADR." It is the same instinct with two additions the ADR format often lacks: the evidence line that admits to "none", and the revisit trigger with an owner. Design's decision-record lessons cover the format; this lesson is about what makes an entry re-decidable (Architecture Decision Records and Decision Records in Design).
- "The journal is for big decisions." It is for decisions above the reversible-in-minutes tier — which includes a lot of medium ones, like where the cart lives, that nobody would write an architecture document for and everybody re-argues.
- "Once the decision is confirmed, the entry can be closed." It stays open with its assumptions, because a confirmed decision is one whose assumptions currently hold, and assumptions move.
Where this applies
Problem-solving advice is stated as universal far more often than it is. These labels say what each method is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view.
- GENERALDecision, evidence, alternatives, why, assumptions, revisit — the six parts are the same for a schema, a provider, a process or a product choice; only the nouns change.
- TEAM-SPECIFICA solo learner's journal is the engineering notebook — the same six parts, read by future-them, and the "owner" of every trigger is the same person; on a team the journal is the thing that replaces three differing memories, and the owner line is what makes a trigger real.
- ILLUSTRATIVEThe cart entry, the six-week gap and the funnel finding are invented; the revisit trigger is left as "a set number of orders" because the real number depends on the store's volume.
Where the depth lives
This domain asks the question and hands the answer off by name.
- — The manifesto's "What Are You Delegating?" cards at /manifesto/delegating are decisions too — each one is a "why" line about what a tool owns and what you keep — and belong in the same journal.