Decision Log Practice
A decision log is a chronological, append-only record of every meaningful product decision: what we decided, what we considered, what evidence we used, and who decided. The format originated in software engineering as the Architecture Decision Record (ADR) — Michael Nygard's 2011 essay defined the canonical structure: title, status, context, decision, consequences. Modern product orgs apply the same pattern to product decisions: pricing changes, feature kills, scope re-cuts, GTM choices. The KnowMBA take: the strongest PMs maintain decision logs that survive personnel turnover. When the original PM leaves, the log is the institutional memory — without it, the next PM re-litigates settled decisions every quarter, and the company quietly forgets why anything is the way it is.
The Trap
The trap is the elaborate decision log nobody updates: a Notion page set up with great intent, three entries from launch week, then nothing for 18 months. The opposite trap is logging everything — every Slack thread, every micro-decision — which produces noise nobody reads. The deepest trap is the politicized log: entries softened to avoid offending stakeholders ('we considered all options carefully' instead of 'sales pushed for X but the metric data didn't support it'). A decision log only works if it's honest enough that future readers can actually understand what happened.
What to Do
(1) Use the ADR template even for product decisions: Title, Date, Decision, Context, Options Considered, Decision Rationale, Consequences, Owner. (2) Log only spec-level or above: pricing changes, feature kills, major scope cuts, GTM bets — not micro-decisions. (3) Keep entries short (300-500 words). (4) Log within 48 hours of the decision, not retroactively. (5) Make it findable: one searchable home, indexed by date and topic. (6) Re-read entries from 6+ months ago each quarter — half will be 'still right,' half will reveal where reality diverged from prediction. That re-read is the org's calibration loop.
In Practice
Michael Nygard's 2011 essay 'Documenting Architecture Decisions' (cognitect.com) introduced the ADR format that has since spread across software engineering and into product practice. Spotify, ThoughtWorks, and GitHub publicly use ADRs. The format is deliberately minimal — context, decision, consequences — to avoid the bureaucracy that killed earlier attempts at design documentation. Nygard's key insight: the value of the log isn't the document itself; it's the COMPRESSION it provides for future engineers (and PMs) trying to understand 'why is this the way it is?' Without the log, that question takes hours of code archaeology and tribal-knowledge interviews. With it, 5 minutes. (Source: Michael Nygard, Documenting Architecture Decisions, 2011)
Pro Tips
- 01
Include a 'consequences' section for every decision — what would change if we were wrong, and what signal would tell us we were wrong. This is what turns a decision log into a learning system rather than a CYA artifact.
- 02
Audit the log every 6 months: pull 5 random entries and ask 'is this still the right call?' If yes, note it. If no, write a new entry that explicitly supersedes the old one (don't edit the old one — appending is what preserves the learning).
- 03
GitLab keeps decision logs in their public handbook. The transparency forces clarity: an entry written for the public can't lean on tribal context, which makes it more useful internally too.
Myth vs Reality
Myth
“Decision logs are bureaucracy — they slow teams down”
Reality
Decision logs ADD ~15 minutes per decision and SAVE hours every time a future team needs to understand why something is the way it is. Past ~50 employees, the log is what prevents the company from re-litigating the same decisions every quarter as new PMs arrive.
Myth
“We have meeting notes — that's enough”
Reality
Meeting notes are chronological and topic-mixed; decision logs are decision-indexed. Try finding 'why did we kill the export feature in 2024?' in 18 months of meeting notes vs. one ADR entry. The two formats serve different purposes; the log is the durable record.
Try it
Run the numbers.
Pressure-test the concept against your own knowledge — answer the challenge or try the live scenario.
Scenario Challenge
A new PM joins your team and asks 'why did we deprecate the Slack integration last year? A customer is asking for it back.' The original PM left 4 months ago. You search Slack and find vague references. There's no decision log entry.
Industry benchmarks
Is your number good?
Calibrate against real-world tiers. Use these ranges as targets — not absolutes.
Decision Log Coverage (% of spec-level decisions logged)
Mid-stage and growth-stage product orgsStrong (Stripe, GitLab pattern)
>80% logged within 48 hours
Healthy
50-80%
Light
20-50%
None
<20% (verbal-only)
Source: Practice norm derived from ADR adoption patterns
Real-world cases
Companies that lived this.
Verified narratives with the numbers that prove (or break) the concept.
Michael Nygard — ADR Essay
2011-present
Michael Nygard's 'Documenting Architecture Decisions' (2011) is the foundational essay for the modern decision-log practice. He proposed a deliberately minimal format (Title, Status, Context, Decision, Consequences) and made the case that the log's value compounds with every personnel turnover. ADRs spread across the engineering community throughout the 2010s and were adopted by ThoughtWorks, Spotify, GitHub, and many others. The pattern has since extended into product organizations as the 'product decision record' or PDR — same format, broader scope.
Original Format
Title, Status, Context, Decision, Consequences
Adoption
ThoughtWorks, Spotify, GitHub, many others
Recommended Length
<1 page per entry
Update Pattern
Append-only
The decision log isn't documentation overhead — it's institutional memory. Every entry is a small bet that future you (or future colleagues) will need to know why something is the way it is. The bet pays out every time.
GitLab — Public Decision Log
2014-present
GitLab embeds decision-log practice directly in their public handbook. Major product, engineering, and operational decisions are documented openly with rationale and considered alternatives. The transparency creates two effects: first, it forces clarity (a public entry can't lean on tribal context); second, it allows competitors and customers to understand GitLab's thinking, which has become part of the company's brand. The handbook receives millions of pageviews per year and is widely cited as the most extensive published example of decision-log discipline at scale.
Handbook Length
2,500+ pages
Decision Records
Public and indexed
Annual Pageviews
Millions
Operating Model
All-remote, async-first
Public-by-default decision logs force the highest level of clarity because the writer can't assume tribal context. Even private decision logs benefit from being WRITTEN AS IF they were public — the discipline forces sharper thinking.
Decision scenario
The Re-Litigated Pricing Decision
Your team killed a usage-based pricing experiment 8 months ago after testing it for a quarter. A new exec joins, asks 'why aren't we usage-based?', and asks you to revisit. There's no decision log entry — just Slack threads.
Decision Age
8 months
Original Test Length
1 quarter
Decision Log Entry
None
New Exec Push to Revisit
Active
Decision 1
You have to either revisit the pricing question fresh or surface the original rationale. Without a log, surfacing the rationale takes effort.
Run a new pricing experiment to satisfy the exec — re-test usage-based for another quarterReveal
Reconstruct the original decision log entry from Slack and interviews — present the data, the alternatives considered, and the rationale to the exec; then commit to logging all future pricing decisions✓ OptimalReveal
Related concepts
Keep connecting.
The concepts that orbit this one — each one sharpens the others.
Beyond the concept
Turn Decision Log Practice into a live operating decision.
Use this concept as the framing layer, then move into a diagnostic if it maps directly to a current bottleneck.
Typical response time: 24h · No retainer required
Turn Decision Log Practice into a live operating decision.
Use Decision Log Practice as the framing layer, then move into diagnostics or advisory if this maps directly to a current business bottleneck.