DEV Community

Fathy Shalaby
Fathy Shalaby

Posted on Originally published at specky.space

Decision Log: How Product Teams Make Every Choice Visible

Most product decisions vanish into Slack. A decision log keeps the reasoning: five fields, three kinds of decision worth logging, and the habits that stop the log going stale.

A decision log is a running record of the choices a team has made: what was decided, the context, the options it rejected, who made the call and when, and what would make the team reopen it. For product teams it is the cheapest fix for re-arguing settled questions, because the reasoning outlives the meeting, the Slack thread and the person who made the call.

Most product teams already write plenty down. The trouble is what they write. A PRD says what you are building, a ticket says how, a roadmap says when. Almost nothing records why this option beat the others, and the why is exactly what people need six months later.

Key takeaways

  • The format comes from software architecture. Michael Nygard's 2011 architecture decision record has five parts (title, context, decision, status, consequences) and fits on one or two pages (Nygard, 2011).
  • Without the reasoning, a newcomer can only accept an old decision blindly or reverse it blindly. Both are risky.
  • Teams already spend over 25% of their workweek searching for information, according to Atlassian's State of Teams 2025 survey of 12,000 knowledge workers (Atlassian, 2025).
  • Log selectively. Jeff Bezos's 2015 letter separates rare, hard-to-reverse "one-way door" decisions from the majority of reversible ones (Amazon 2015 letter, via SEC). Five fields and a review trigger are enough.
  • Keep it append-only. When a decision changes, write a new entry that supersedes the old one rather than editing history (Microsoft Learn, 2026).

What is a decision log?

A decision log is a list of entries, one per significant decision, kept in one place the whole team can search. Each entry records a conclusion, not a conversation. That is what separates it from meeting notes, which capture what was said, and from a PRD, which captures what will be built.

The idea is older than most product teams. In November 2011 Michael Nygard proposed the architecture decision record (ADR): a short document per decision, numbered sequentially, with numbers never reused, stored next to the code. A reversed decision is not deleted. It is marked superseded and points to its replacement, because the fact that it once applied is still useful (Nygard, 2011).

The practice has since spread well beyond engineering blogs. In November 2025 the UK's Department for Science, Innovation and Technology and the Government Digital Service published an ADR framework for the public sector. It asks each record for eight elements: title, date, status, context, decision, consequences, stakeholders consulted and links to supporting documents (GOV.UK, 2025).

A product decision log applies the same discipline to product choices: scope, sequencing, target segment, pricing, and bets that rest on beliefs you haven't tested yet.

How does a decision log differ from other records?

Record Question it answers Written when Usually owned by
Decision log entry Why did we choose this, and what would change our mind? At the moment of decision The person who made the call
Architecture decision record Why is the system built this way? When a technical choice is made An engineer or architect
Meeting notes What was said? During or after a meeting Whoever took notes
PRD or spec What are we building, and for whom? Before the build The PM

The records work best linked together. If you need the comparison with tickets and roadmaps too, the product decision log template covers it alongside a copyable template.

Why do product decisions keep disappearing?

The problem is rarely discipline. Most PMs keep something: a Notion page, a Confluence doc, a comment on a Jira ticket. But those records describe artefacts, and the reasoning lives in a thread, a call or one person's head.

When the why is missing, two things go wrong.

The team can't update decisions intelligently. If nobody knows why a choice was made, nobody can tell whether the original reason still holds. Nygard describes the two bad options a newcomer faces: accept the decision blindly, and risk keeping something that no longer fits, or reverse it blindly, and risk breaking whatever it was protecting. His conclusion is blunt: "It's better to avoid either blind acceptance or blind reversal."

New people re-derive instead of learning. They re-run debates that were settled, and repeat mistakes that were made and never written down. Microsoft's architecture guidance puts it plainly: a decision that is made but never recorded will probably be forgotten, which leads to repeated debates or later changes that quietly contradict the original intent (Microsoft Learn, 2026).

The search cost is real. Atlassian's 2025 survey found teams spend over 25% of their week looking for information, and that Fortune 500 teams waste 2.4 billion hours searching for information (Atlassian, 2025). Not all of that is missing decision context, but "why did we do it this way?" is one of the most expensive questions to answer from memory.

What should a decision log include? The five fields

The format matters less than the fields. An entry that earns its keep has five.

1. The decision statement

One sentence stating the conclusion, not the discussion. "We will prioritise onboarding completion over feature discovery in Q3." "We will not build a mobile app until web reaches 500 daily active users." The statement is the headline; everything else supports it. Make it specific enough to be wrong.

2. The context

What made the decision necessary? A customer complaint, a metric dip, a competitor's move, a change in strategy. Two to four sentences, enough for someone who wasn't in the room to understand why the question came up at all. Link the evidence rather than paraphrasing it.

3. The options considered

List the realistic alternatives, including the ones you rejected and "do nothing yet" when it was viable. This is the most skipped field and the most valuable one. It shows the decision was deliberate, and it stops the same rejected option being proposed as new next quarter. Microsoft's guidance makes options considered and trade-offs part of every record for the same reason.

4. The owner and the date

Who made the call, and when. This isn't about blame. It is about knowing whom to ask when the question resurfaces. One name works better than a committee: Bain's RAPID framework, for example, says there should ideally be only one decider for each decision (Bain).

5. The review trigger

What would make you revisit this? "If web DAU passes 500." "If three or more enterprise customers ask for mobile in Q4." The trigger turns a static record into a live one. Decisions without triggers harden into rules that everyone follows long after the reason expired.

Weak and strong entries side by side

Field Weak entry Strong entry (illustrative)
Decision "Discussed mobile." "No native mobile app before web reaches 500 DAU."
Context "Customers want mobile." "3 of 40 recent interviewees asked; all three use the web app daily."
Options (blank) "Native app; responsive web; progressive web app. Chose responsive web."
Owner and date "Team" "Founder, 4 March"
Review trigger (blank) "Web DAU above 500, or 3+ enterprise requests in one quarter."

Two optional fields pay off quickly: a status (proposed, decided, testing, superseded) and a confidence level with one line explaining it. Microsoft recommends recording confidence because a low-confidence decision is the first one to reconsider when circumstances change.

Which decisions belong in a decision log?

Not every micro-decision belongs in the log. If you log everything, nobody reads it, and the log becomes another graveyard of good intentions. Three categories earn their place every sprint.

Scope decisions. Any time you cut something from a release, delay a feature or narrow a brief. An illustrative entry: "We cut bulk export from v1.3 because it added three weeks of backend work and 8% of survey respondents asked for it." That one line prevents two future arguments: "why didn't you build export?" and "should we build it now?"

Direction changes. Any time you reverse an earlier decision, override a stakeholder request, or depart from what was agreed in planning. The log turns "I thought we agreed to X" into "we agreed X in week 4, then changed to Y in week 7 because of Z." That isn't politics; it's operational hygiene.

Bets with uncertain payoff. Any call based on a belief you haven't validated: "we think teams will upgrade if we add collaboration." Record the evidence you had at the time. Three months later you can compare what you believed with what happened, which is how a team's judgement improves.

A quick filter

Bezos's 2015 letter describes one-way doors, consequential and nearly irreversible, which deserve slow, careful deliberation. He argues most decisions are two-way doors that a small group should make quickly (Amazon 2015 letter, via SEC). Use that split to set the depth of the entry:

  • Full entry: one-way doors, such as pricing, data model, a new customer segment, killing a feature, or anything over two weeks of build.
  • One line: two-way doors, such as copy changes, small UX tweaks or internal tooling. Note the choice and the trigger.
  • Nothing: implementation details that belong in the ticket.

The one-way vs two-way door framework goes deeper on judging reversibility before you decide.

How do you keep a decision log from going stale?

The graveyard of product documentation is full of logs created once and never touched again. The difference between a living log and a dead one is almost always process, not tooling.

  1. Anchor it to the sprint retrospective. Spend five minutes at the end of each retro on one question: what did we decide in the last two weeks that isn't written down? Log the answers. That keeps the log current without turning it into a job.
  2. Link it from your PRDs. Give every PRD a "Related decisions" section linking the entries behind its scope. A new engineer can then trace each major scope choice back to its reasoning. Our guide on how to write a PRD shows where that section fits.
  3. Check review triggers in sprint planning. At the start of each sprint, scan for triggers that are now true. "We said we'd revisit mobile at 500 DAU, and we hit 600 this week." That turns the log from a passive record into an input to planning.
  4. Supersede, don't edit. When a decision changes, write a new entry, mark the old one superseded, and link the two. Microsoft calls this an append-only log; Nygard did the same in 2011. The history shows when and why the direction shifted.
  5. Don't wait for the perfect format. The most common way decision logs fail is a two-week argument about the template, followed by no habit at all. A shared document with five columns beats a perfect database nobody fills in.

How do async and remote teams use a decision log?

For partly or fully remote teams, the log stops being a nice-to-have and becomes the place decisions actually exist.

In an office, decisions spread by proximity: someone overhears, someone asks at lunch. In a distributed team, a decision that isn't written down doesn't exist for whoever was offline when it was made. Basecamp's public communication guide makes the same point in four words: "Writing solidifies, chat dissolves." It also argues that speaking only helps whoever is in the room, while writing helps everyone, including future hires (Basecamp).

A simple async decision process built on the log:

  1. Propose. The owner writes the entry with status "proposed", including options and evidence.
  2. Comment window. Teammates have 48 hours to comment. Across time zones, that gives every location at least one full working day to respond.
  3. Decide. The single named owner makes the call and changes the status to "decided", noting which objections they accepted and which they didn't.
  4. Commit. People who disagreed still commit. Bezos's 2016 letter recommends exactly this, "disagree and commit", as a way to save time when a decision has been argued but not agreed (Amazon, 2017).

The comment window replaces the meeting. The structured entry replaces the minutes. And onboarding a new teammate becomes a matter of reading, not of interviewing every veteran.

What evidence should a decision log entry cite?

An entry without evidence is a record of preferences. What separates a good entry from a weak one is the evidence it links. Product evidence falls into four groups, roughly in order of reliability.

Behavioural data. Usage metrics, funnels, cohorts. For example (illustrative): "Users who use collaboration in their first session retain at day 30 at nearly twice the rate of those who don't." It is the strongest evidence because it reflects what people do, not what they say.

Qualitative research. Interview notes, support tickets, sales call notes. Weaker for "how many" claims, but often the only source for why something is happening: "Three enterprise prospects asked about audit logs in sales calls this month."

Competitive signals. What competitors shipped and, where you can actually see it, what happened next. Useful context, never a sufficient reason on its own.

Assumptions. Things you believe but haven't tested. Label them: "We assume cutting onboarding from 7 steps to 4 will raise day-1 completion. Untested." Every bet entry should separate evidence from assumption and say how you'll find out.

You will rarely have complete evidence. Bezos's 2016 letter suggests most decisions should be made with about 70% of the information you wish you had, and that waiting for 90% usually means being slow. A useful habit: write down what the missing 30% would need to show to change your mind, and make that the review trigger. For what counts as evidence against each type of product risk, see the four product risks.

Worked example: one quarter of a product decision log

Say a 6-person B2B SaaS team starts logging decisions in week 1 of a quarter. This is an illustrative team, not a real company.

Week Entry Type Review trigger What happened
2 No native mobile app before web reaches 500 DAU Scope Web DAU above 500 Trigger fired in week 11 at 600 DAU
5 Cut bulk export from v1.3 (3 weeks of backend, 8% of respondents asked) Scope Export requested in 5+ sales calls 2 requests by quarter end; stays cut
7 Prioritise onboarding completion over feature discovery for Q3 Direction change Day-1 completion flat after 6 weeks Reviewed in week 13
9 Cut onboarding from 7 steps to 4, expecting day-1 completion to rise from 38% to 50% Bet Result after 4 weeks of sign-ups Reached 44%: partly right, follow-up bet logged

Two moments show the payoff. In week 11, when web DAU crossed the threshold, sprint planning reopened the mobile question with the original reasoning, the rejected options and the three interview quotes already on the page. The discussion started from "what has changed?" rather than from scratch.

In week 13 the onboarding bet landed between failure and success. Because the entry recorded the expected 50%, the team could see the gap honestly instead of declaring victory at 44%. They wrote a new entry superseding the first, rather than editing the original target after the fact.

Common mistakes, and when a decision log doesn't help

  • Logging everything. A log of 200 entries with 180 trivial ones is unreadable. Use the one-way and two-way door filter.
  • Conclusions without options. If the rejected alternatives aren't there, the next person will propose them again as new ideas.
  • Writing it after the fact. Reconstructed reasoning is flattering reasoning. Write the entry when you decide.
  • Editing old entries. Changing the original target once the result is in destroys the one thing the log is for: comparing what you believed with what happened.
  • No owner. "The team decided" means nobody can answer follow-up questions.
  • Using it as a weapon. "You agreed in week 4" ends conversations. The log should make it easy to change your mind for a stated reason.

A log won't fix a team where decisions are really made elsewhere, by whoever is most senior in the room. It records decisions; it doesn't create decision rights. And for a solo founder in the first few weeks, a full five-field entry is overkill: a dated one-line list of choices with triggers is enough until a second person needs the context.

Three things to do this week

  1. Start the log. Open a shared document with five columns (Decision | Context | Options considered | Owner and date | Review trigger) and log the last three significant calls your team made. That is your log.
  2. Add a "Related decisions" section to your next PRD. Link every scope choice back to an entry. It forces you to state the reasoning behind each requirement.
  3. Add five minutes to your next retrospective. Ask what you decided this sprint that isn't written down. Log the answers. Repeat until it's reflexive.

Where Specky fits

Specky has a Decision Log built into the workspace. Each entry records what was decided and why, carries a status (active, superseded or reversed) and an outcome you update after launch, and links to the customer evidence in the Product Graph that informed it. You can log a decision by hand, ask the AI to draft one with you, or extract decisions from an existing PRD. A person still makes and owns every call. For a broader model of linking signals, decisions, work and outcomes, see our piece on the decision graph for small AI teams.

Frequently asked questions

What is a decision log in product management?

A decision log is a searchable record of significant product decisions, with one entry per decision covering what was decided, the context, the options rejected, the owner and date, and the condition that would reopen it. It preserves the reasoning behind scope cuts, direction changes and bets, so the team doesn't re-argue settled questions or lose context when people leave.

What is the difference between a decision log and an architecture decision record?

An architecture decision record covers one technical choice about how a system is built; Michael Nygard's 2011 format has title, context, decision, status and consequences. A product decision log uses the same structure for product choices such as scope, segments, pricing and bets. Many teams keep both and link them when a product decision drives a technical one.

How long should a decision log entry be?

Most entries fit in five to ten lines: one sentence for the decision, two to four for context, one line per option, the owner and date, and a review trigger. Nygard suggested one or two pages for an architecture record as the upper limit. If you need more, link to a research note or brief rather than copying it in.

Who should own the decision log?

The PM or founder usually owns the log itself, but each entry should name the single person who made that decision. Shared ownership of the log works; shared ownership of individual decisions doesn't, because nobody can then answer follow-up questions. A quick five-minute check in each retrospective keeps the log complete.

How often should a team review its decision log?

Check review triggers at the start of every sprint, and add new entries at the end of every retrospective. A deeper quarterly pass is worth doing too: mark expired decisions as superseded and compare the outcomes of bets against what the team expected. That comparison is what improves future judgement.

Should you log decisions that turned out wrong?

Yes, and those entries are often the most useful ones. Mark the decision as reversed or superseded, link the entry that replaced it, and record what you learned. Deleting wrong decisions hides exactly the history that stops a team from making the same mistake twice.

Sources

  1. Michael Nygard, Cognitect — Documenting Architecture Decisions (2011)
  2. Amazon — 2015 Letter to Shareholders, via SEC EDGAR (2016)
  3. Amazon — 2016 Letter to Shareholders (2017)
  4. Atlassian — How the Atlassian System of Work connects distributed teams, citing State of Teams 2025 (2025)
  5. Basecamp — How we communicate
  6. Microsoft Learn — Maintain an architecture decision record (2026)
  7. GOV.UK, DSIT and Government Digital Service — Architectural Decision Record Framework (2025)
  8. Bain & Company — RAPID decision-making framework

This story was originally published on 11 July 2026 at https://www.specky.space/blog/pm-decision-log-make-choices-visible.

Top comments (0)