Keep the decision log inside the spec because that's where anyone re-checking a choice will actually look. A short section listing rejected options, the decision, and the reasoning stops repeat debates, cuts onboarding time, and keeps rationale attached to the artifact it shaped instead of scattered across Slack threads and stale meeting notes.
A decision record needs five things: context, options considered, the decision itself, rationale, and a date. Store it as a section inside the spec, update it via diffs when circumstances change, and point to it the next time someone asks "wait, didn't we already decide this?"
Why Rejected Options Vanish the Moment the Meeting Ends
Teams don't re-litigate decisions out of malice. They re-litigate because the reasoning left the room and never came back. Six weeks after you dropped the multi-tenant option for a simpler single-tenant design, a new engineer proposes multi-tenant again — not as a challenge, but because nothing visible says it was already considered and rejected.
This is not a memory problem you can fix by writing better meeting notes. It's a location problem. The rationale exists somewhere — a Slack thread, a Zoom recording, someone's head — but none of those places are where a future reader looks when they open the spec and start asking questions.
A few patterns make this worse:
- Turnover. The person who remembers the debate leaves the team; the decision becomes unexplainable folklore ("we just don't do it that way").
- Time. Even the original decider forgets the specifics after two or three sprints of context-switching.
- Tool sprawl. The decision lived in a meeting, then a Slack thread, then a comment on a ticket — three artifacts, none of them the spec, none of them searchable together.
- Success amnesia. Once something ships and works, the objections that almost stopped it look, in hindsight, unreasonable — so the "why not" gets dropped first.
Jeff Bezos's well-known distinction between one-way doors (decisions that are hard or costly to reverse) and two-way doors (cheap to reverse) is useful here, drawn from Amazon's 2016 shareholder letter. One-way-door decisions are exactly the ones worth recording carefully, because reopening them without the original context wastes the most time and carries the most risk. Two-way-door decisions barely need a record at all — that judgment call is worth making explicit before deciding what earns a log entry.
The Five-Field Decision Record: A Format Light Enough to Actually Use
A decision record works only if writing one takes less time than re-litigating the decision would. Keep it to five fields, filled in at the moment the decision is made — not reconstructed later from memory.
| Field | What it captures | Why it matters later |
|---|---|---|
| Context | The problem, constraint, or trigger that forced a choice | Stops "why did we even need to decide this?" |
| Options considered | Every real alternative, including the ones dismissed in five minutes | Proves the obvious alternative was considered |
| Decision | The one-sentence outcome, stated plainly | Gives skimmers the answer without reading rationale |
| Rationale | The specific tradeoff that tipped it — cost, risk, timeline, a user signal | Is the actual re-litigation-preventer; everything else is scaffolding |
| Date (and owner) | When and who | Anchors it in time so staleness is visible |
This is a compressed cousin of Michael Nygard's Architecture Decision Record (ADR) pattern, first documented in 2011 and since adopted widely enough that ThoughtWorks' Technology Radar has flagged it as a mainstream practice for engineering teams. Nygard's original format includes a "Consequences" field; for product decisions, folding consequences into rationale keeps the record to five fields instead of six, which matters more than it sounds — every extra required field is a reason someone skips writing the record at all.
What "options considered" actually needs
The most re-litigated decisions are ones where the record states only what was chosen, not what was rejected. Anyone can propose the option you dropped as if it were new — because as far as they can tell, it is new. List every option seriously discussed, even the one killed in the first two minutes of a meeting, with one clause on why:
- Option A (chosen): single-tenant architecture — simpler ops, faster to ship for the current customer count.
- Option B (rejected): multi-tenant from day one — adds three weeks and a migration risk we don't need until we pass 200 customers.
- Option C (rejected): a hybrid schema-per-tenant model — solves a scaling problem we don't have yet, at a complexity cost we'd pay immediately.
Three lines. Anyone proposing Option B again in six months reads line two and either finds a genuinely new argument or drops it — either way, the conversation starts from where it left off instead of from zero.
Grounding context in the job, not the feature
A context field reads best when it names the underlying job, not just the feature request. If the trigger for a decision was a specific customer job the product needed to satisfy, say so explicitly — the framing behind our Jobs-to-be-Done guide is a useful discipline here, because "the job was X" survives reorganizations and roadmap pivots better than "the ticket was X."
Where the Decision Log Should Live: In the Spec, Not in Slack
The decision log belongs inside the spec section it affects, not in a separate decisions doc, a Slack channel, or a wiki page nobody bookmarks. Proximity is the whole point — a reader questioning a requirement should find the rationale one scroll away, not a Slack search away.
| Location | Discoverable by future readers? | Survives tool migrations? | Stays attached to the requirement it explains? |
|---|---|---|---|
| Slack thread | No — buried in minutes | No | No |
| Meeting notes doc | Rarely — separate doc, separate search | Sometimes | No |
| Standalone "decisions" wiki page | Sometimes, if maintained | Sometimes | No — decoupled from the spec |
| Section inside the spec | Yes — same document, same search | Yes, if the spec itself is durable | Yes — sits right next to the requirement |
Every alternative to "inside the spec" adds a lookup step, and every lookup step is a reason someone skips checking and just re-argues the point live in a meeting instead. A living spec is meant to be the one artifact people trust as current — that trust is exactly what makes a decision log inside it credible, instead of one more doc people assume is stale.
How the log matures alongside the rest of the spec
Not every section of a spec is equally settled at every point in a project, and the decision log is no exception — a discipline covered in more depth in our piece on section-level maturity in a living spec. Early on, a decision might carry a "provisional" tag because you're choosing under incomplete information. As evidence accumulates, promote it to settled and drop the caveat. The point isn't to freeze decisions early — it's to make their confidence level visible, not just their content.
This maturity signal also feeds directly into release gating. A requirement with an open, unresolved decision attached to it shouldn't be treated as settled — which is exactly the distinction our guide to ready-to-start versus ready-to-ship gates draws: a section can be ready to start work against while its decision log still has open questions, but it isn't ready to ship until those close out.
A short note on how Prodinja handles this
Spec Studio's anchored comments and diffs are designed to capture why a spec section changed, at the moment it changes — so the rationale sits attached to the requirement instead of living only in a Slack thread you'd have to dig up later. That's the same principle this whole article argues for; the tool just gives the habit a place to attach to, instead of requiring separate discipline to maintain a decisions doc on the side.
Updating the Log Without Rewriting History
A decision log stays useful only if updates add to it instead of silently overwriting it. When a decision changes, don't delete the old entry — append a new one that references the old, with the date and the new rationale, so the log shows the sequence of reasoning, not just the current state.
Treat every change to the decision log the way you'd treat a code change: as a diff with a visible author, timestamp, and reason, reviewable before it merges into the spec. Our guide on PR-style spec diffs and review covers this pattern in detail — the same discipline that stops silent, unreviewed edits to requirements applies just as well to decisions about those requirements.
A minimal update entry needs only three things beyond the original five fields:
- What changed — one line naming the prior decision by date, so the thread is traceable.
- Why now — the new evidence, constraint, or failure that reopened the question.
- What stays true — explicitly note if the original rationale still holds for some sub-case, so you don't accidentally imply the whole prior decision was wrong.
This matters because reversed decisions carry the highest re-litigation risk of all. If Option B gets picked after all, eighteen months later, and the log simply erases the old entry, nobody can tell whether the team learned something new or just forgot the reasons it said no the first time.
What a Visible Decision Log Buys You
A decision log earns its keep in two currencies: time saved not re-arguing settled questions, and speed gained onboarding new people who need the "why" behind the "what." Both compound — the second time a decision would otherwise be re-litigated, the log pays back the five minutes it took to write.
Bain & Company's long-running research into decision effectiveness, published by Paul Rogers and Marcia Blenko in their Harvard Business Review piece "Who Has the D?" (2006), found that organizations clear about who decides and why consistently outperform peers on execution speed. The inverse of that clarity is exactly the ambiguity a missing decision log creates — their broader point, that decision rights and rationale are organizational infrastructure rather than an afterthought, applies just as well at the level of a single product spec.
Google's internal "design docs" practice, described publicly by engineer Malte Ubl in a widely shared 2020 write-up, makes a related point: writing down the alternatives considered — not just the chosen approach — is treated as one of the document's core jobs, not an optional appendix. A spec's decision log is the product-management equivalent of that same discipline.
A worked example: cutting an onboarding step
Say a customer journey emotion curve shows a spike in frustration at the account-verification step, and the team debates cutting it entirely versus simplifying it. The decision record — informed by the mapping approach in our customer journey guide — might read: context (verification scored lowest on the emotion curve; users cited it as the reason for dropoff), options (remove entirely, simplify to one field, keep as-is with better copy), decision (simplify to one field), rationale (removing it entirely raised fraud risk beyond what the team could accept; leaving it as-is left the friction unaddressed).
Six months later, when a support escalation raises the question "why do we even ask for this at signup?", the answer is one scroll away instead of a re-run debate.
Common Mistakes That Quietly Undo a Decision Log
Most decision logs fail not because nobody writes them, but because of a handful of habits that hollow them out over time. Watch for these:
- Only recording the decision, not the rejected options. Without the alternatives, the log can't stop anyone from re-proposing them.
- Vague rationale. "It made more sense" tells a future reader nothing; "it cut integration time from six weeks to two, and we don't yet have the customer volume to justify the alternative" does.
- No date. A decision from fourteen months ago, made under assumptions that no longer hold, reads as current if it isn't dated — and gets treated as settled when it should be revisited.
- Letting it live outside the spec "for now," with a plan to migrate it later that never happens.
- Overwriting instead of appending. Losing the history of why a decision changed is almost as costly as never recording the first decision at all.
- Writing it retroactively, days after the meeting. Memory degrades fast; the record is only as good as how soon after the decision it's captured.
If your team also uses something like Prodinja's Journals to capture assumptions and reflections in the moment, including real voice capture, those raw notes are a good source for a decision entry. The entry itself still belongs distilled into the spec, not left scattered across separate journal notes.
Key Takeaways
- Re-litigation is a location problem, not a memory problem — the reasoning existed, it just wasn't where anyone would think to look for it.
- Use a five-field format: context, options considered, decision, rationale, date — light enough that people will actually fill it in.
- List every seriously considered option, including ones dismissed quickly, so nobody can propose them as if they were new.
- Keep the log inside the spec itself, not in Slack, meeting notes, or a separate wiki page — proximity to the requirement is what gets it checked.
- Update via diffs, not overwrites — append new entries that reference prior ones so the sequence of reasoning stays visible.
- Reserve the most careful documentation for one-way-door decisions — the ones costly to reverse — and don't over-invest in logging trivial, easily-reversed ones.
- A visible decision log speeds onboarding as much as it prevents arguments — new hires read the "why," not just the "what."
Frequently Asked Questions
What should a product decision log include?
A product decision log should include five fields: context (the problem or trigger), options considered (every real alternative, including quickly-dismissed ones), the decision itself, rationale (the specific tradeoff that decided it), and a date. Anything beyond these five tends to slow adoption without adding much value.
Where should a spec decision record live?
A spec decision record should live inside the spec section it affects, not in a separate document, Slack thread, or wiki page. Co-locating it with the requirement it explains is what makes a future reader actually find and trust it, instead of re-arguing the point from scratch.
How do you stop a team from re-litigating a settled decision?
You stop re-litigation by making the rejected options and rationale visible in the same place someone would look when questioning a requirement — typically the spec itself. Once the "why not" is one scroll away, most repeat debates end the moment someone reads the existing entry.
Should every decision get a full decision record?
No — reserve detailed records for decisions that are costly or slow to reverse, sometimes called one-way-door decisions. Cheap, reversible calls barely need more than a one-line note, if that; over-documenting trivial choices trains a team to stop reading the log at all.
How is a decision log different from meeting notes?
Meeting notes capture everything discussed, in chronological order; a decision log captures only the outcome, the alternatives, and the reasoning, organized by the requirement it affects rather than by when the conversation happened. Notes decay into noise; a well-kept decision log stays useful for as long as the spec does.