A short, structured record of one decision. Optimized for "future-you reading this in 6 months" — what changed, why, and what you'd need to know to reconsider.
When to use
- An ADR (architecture decision record) for an engineering pick
- A product call where the path-not-taken matters
- An ops/policy change that future maintainers will hit
Skip for: pure code reviews (the diff is the record), small reversible tweaks (the commit message is enough), brainstorming sessions before a decision is made.
Workflow
State the decision in one sentence. Past tense, declarative. "We chose Postgres over DynamoDB for the v1 marketplace data store." Not "We will use" or "We are considering."
Context: what forced the decision. 2–3 sentences. What was the situation that made this a fork in the road? What constraint or goal was load-bearing?
Alternatives considered. Bullet list, 2–4 items. For each: one line on what it was, one line on why it lost. The losers matter more than the winner for future-you.
Trade-offs accepted. What did the chosen path cost us? Be specific. "Slower writes than DynamoDB at >10K QPS, accepted because v1 traffic is single-digit QPS." Hand-waving here defeats the purpose.
Reversibility + revisit date. Two lines:
- Reversibility: cheap / medium / expensive (and roughly why).
- Revisit: a specific event ("when we hit 100 paying customers") or a date ("Q3 2026"). Without a revisit cue, decision logs become dead text.
Owner. One name. The person who picks up the revisit and writes the follow-up entry.
Template
# <Decision title>
**Date:** YYYY-MM-DD
**Owner:** <name>
**Decision:** <one sentence, past tense>
## Context
<2–3 sentences. What forced the fork?>
## Alternatives considered
- **<option A>** — <one line>. Lost because <reason>.
- **<option B>** — <one line>. Lost because <reason>.
## Trade-offs accepted
- <thing we gave up + why we're OK with it>
## Reversibility
<cheap | medium | expensive>. <one-sentence rationale>
## Revisit
<event or date>
Definition of done
- One sentence summary, past tense
- At least 2 alternatives with their lose-reasons
- Explicit reversibility note
- A real revisit cue (not "as needed")
- Owner named
Gotchas
- The retro is not the decision log. Don't write the postmortem here. The log captures the call as made; the postmortem captures how it played out.
- Don't lie about alternatives. If only one option was seriously considered, say so — and explain why. Fake "we considered X" entries fool no one and dilute future signal.
- Reversibility is the most important field. Cheap-to-reverse decisions get less rigor; expensive ones deserve more analysis upfront. Mislabeling reversibility is the most common mistake.
- Revisit dates rot. If your log has six entries with revisit dates that have passed and no follow-up, the system is broken — fix the rhythm, not the template.
- One decision per entry. "We're switching to Postgres AND deprecating the v0 API AND renaming the service" is three decisions. Split them.