Benefit, cost, alternative, reason
coreintermediateEvery significant design decision gets four sentences. The benefit: what improves, in a number where one exists. The cost: what gets worse, also concretely — money, latency, staleness, operational work, a rule you can no longer enforce in one place. The alternative: the option you did not take. The reason: why this benefit was worth this cost here, for this system, at this scale. Most write-ups carry only the benefit, which is why they read as advocacy rather than analysis. The cost is what makes the decision honest, and stating it is not a weakness in the proposal — a decision with no stated cost has either not been examined or is not a trade-off at all. The alternative is what makes the decision revisitable: eighteen months later, someone asking "why is it built this way" can see what was already considered and rejected, instead of re-running the whole argument from scratch or, worse, switching to the alternative for reasons that were already known and dismissed. And the reason has to be specific to this system. "Microservices scale better" is a fact about microservices. "We split billing out because it needs a different deploy cadence and a different on-call rotation than the rest" is a reason.
Think of it as
A receipt, not a sales pitch. A receipt names what you got, what you paid, and it exists so that later — when someone asks whether the purchase made sense — the answer does not depend on anyone remembering. The alternative is the item you put back on the shelf, written down so nobody carries it to the till again next month.
What we're doing: Turn a one-line proposal into a decision record a reviewer can disagree with.
- 15
- The benefit carries two numbers and their source — a measured provider p99 and the resulting endpoint p99. A reviewer can challenge either one, which is the point.
- 20
- The cost includes operational work, not just a technical property. New things to monitor and a harder debugging path are real costs that proposals routinely leave out.
- 33
- The reason explains why the alternative loses on its own terms rather than dismissing it. That is what stops the team from re-proposing it in six months.
- 40
- A "revisit when" line is optional but cheap: it converts a decision that will silently expire into one with a stated trigger.
Why this works: The rewritten version is not longer for the sake of ceremony. Each part removes a specific future failure: the benefit gives something to measure against, the cost stops the eventual-consistency surprise from reading as a bug, the alternative stops it being re-litigated, and the reason ties the choice to this system rather than to a general belief about queues.
Writing the reasoning after the decision has shipped
Wrong
Better
What you see: Every past decision has a rationale, every rationale sounds sensible, and none of them predict anything — because each was written to explain what already exists rather than to choose between options that were still open.
Why: Reconstructed reasoning is a guess about your own past. It reliably drops the alternatives, because the one that was chosen is the only one still visible, and it reliably converts discovered benefits into stated goals. The record then teaches the next decision the wrong lesson.
- Whole: BENEFIT p99 profile read 240ms -> 30ms COST reads may lag the primary by 8s ALTERNATIVE scale the primary vertically REASON profiles tolerate stale; checkout does not
- BENEFIT — What improves: Named with a number wherever one exists. "Much faster" cannot be checked later; "240 ms to 30 ms" can.
- COST — What gets worse: The part most write-ups omit. Without it the document is advocacy, and the cost still arrives — just as a production surprise instead of a decision.
- ALTERNATIVE — What you did not take: Makes the decision revisitable. A future reader sees what was already considered instead of switching to it for reasons already known.
- REASON — Why the trade was right here: Specific to this system and this scale. A general property of the technology is a fact, not a reason.
The four parts, and what their absence looks like months later
The same decision, stated two ways
Remember: Four sentences per significant decision: benefit (what improves, with a number where one exists), cost (what gets worse — money, latency, staleness, operational work), alternative (what you did not take), reason (why this trade was right for this system at this scale). The cost is what makes it analysis rather than advocacy; the alternative is what makes it revisitable. Write it at decision time — reasoning reconstructed later drops the alternatives and turns discovered benefits into stated goals.
See also: the recurring trade offs · pattern tradeoffs · when not to split · the high level design checklist · start with requirements not technologies

