What This Template Is For
Product teams make dozens of decisions every month. Most of them live in Slack threads, meeting notes, and the memories of whoever was in the room. Three months later, someone asks "Why did we build it that way?" and nobody can reconstruct the rationale. The decision gets revisited, relitigated, and sometimes reversed without anyone realizing the original tradeoffs still apply.
A decision log is a running register of significant product decisions. Each entry captures what was decided, the context at the time, the alternatives that were considered, the rationale for the chosen path, who made the decision, and who was consulted. It is not a project management tool or a meeting transcript. It is an institutional memory system that prevents your team from relearning the same lessons and revisiting the same debates every quarter.
This template is especially useful during periods of organizational change (new leadership, team restructuring, acquisition) when context about past decisions is easily lost. For frameworks that help you make better decisions in the first place, see the Decision Matrix entry for structured evaluation methods. For strategy-level decisions that shape long-term direction, the Product Strategy Handbook covers how to set and communicate a coherent strategy.
When to Use This Template
- When you make a significant product decision. Not every decision belongs in the log. Log decisions that affect architecture, pricing, roadmap direction, partnerships, major UX changes, or team structure. Skip tactical decisions like which Jira ticket to work on first.
- When a decision involves tradeoffs. If there were two or more reasonable options and you chose one over the others, the rationale is worth documenting. Future team members will face the same tradeoff and need to understand why you chose the way you did.
- When multiple stakeholders are involved. Cross-functional decisions (product + engineering + sales + legal) are the most likely to be misremembered or disputed later. The log creates a shared record that all parties can reference.
- During post-mortems and retrospectives. Review the decision log to understand which decisions contributed to outcomes, both good and bad. This turns post-mortems from blame sessions into learning opportunities.
- When onboarding a new team member. Instead of explaining "why we do things this way" verbally for every architectural choice and product decision, hand them the decision log. It is the fastest way to transfer institutional knowledge.
- At quarterly planning boundaries. Review the log at the start of each quarter to revisit decisions that were flagged for review. Some decisions have a natural expiration date as conditions change.
How to Use This Template
- Log decisions within 24 hours. Do not batch decision logging for the end of the sprint or the end of the quarter. The context fades quickly. After a meeting where a significant decision is made, spend 5-10 minutes filling in a new row before you close your laptop.
- Include the alternatives you rejected. This is the most commonly skipped field and the most valuable one for future readers. Knowing that you considered Option B and rejected it because of X prevents someone from proposing Option B again six months later without new information.
- Name the decision maker and the stakeholders consulted. This is not about blame. It is about accountability and traceability. When someone wants to revisit a decision, they know who to talk to for the original context.
- Set a review date for reversible decisions. Not every decision is permanent. If you chose a vendor, a pricing model, or a technical approach with the expectation that you would revisit it in 6 months, set a review date so it does not fall through the cracks.
- Keep the log in a shared, searchable location. A Google Sheet, Notion database, or Confluence page works well. The format matters less than the accessibility. If people cannot find the log, they will not use it.
The Template
Decision Log Table
| Decision ID | Date | Decision | Context | Alternatives Considered | Rationale | Decision Maker | Stakeholders Consulted | Status | Review Date |
|---|---|---|---|---|---|---|---|---|---|
| D-001 | [YYYY-MM-DD] | [Clear, concise statement of what was decided] | [What was happening that required this decision? 2-3 sentences.] | [Option B: ..., Option C: ...] | [Why this option was chosen over the alternatives. Reference data, user research, or business constraints.] | [Name and role] | [Names and roles] | [Active / Superseded / Reversed / Under Review] | [YYYY-MM-DD or "None"] |
| D-002 | |||||||||
| D-003 | |||||||||
| D-004 | |||||||||
| D-005 |
Status Definitions
| Status | Meaning |
|---|---|
| Active | The decision is in effect and being followed. |
| Superseded | A newer decision has replaced this one. Link to the new decision ID. |
| Reversed | The decision was explicitly reversed. Document why in a new entry. |
| Under Review | The review date has arrived or conditions have changed. The decision is being reevaluated. |
Decision Entry Template (Expanded Format)
For high-stakes decisions that need more than a table row, use this expanded format.
Decision ID. [D-XXX]
Date. [YYYY-MM-DD]
Decision. [One sentence. What did you decide?]
Context.
[2-3 paragraphs. What was happening that required this decision? What problem were you solving? What constraints existed? What data or research informed the options?]
Alternatives Considered.
| Option | Description | Pros | Cons |
|---|---|---|---|
| A (Chosen) | [Description] | [Pros] | [Cons] |
| B (Rejected) | [Description] | [Pros] | [Cons] |
| C (Rejected) | [Description] | [Pros] | [Cons] |
Rationale.
[Why was Option A chosen? What was the deciding factor? Reference specific data points, user research, technical constraints, or business goals.]
Decision Maker. [Name, Role]
Stakeholders Consulted. [Name (Role), Name (Role), Name (Role)]
Risks and Mitigations.
- [Risk 1: ...] Mitigation: [...]
- [Risk 2: ...] Mitigation: [...]
Status. [Active / Superseded / Reversed / Under Review]
Review Date. [YYYY-MM-DD or "Not applicable"]
Related Decisions. [D-XXX, D-XXX]
Decision Review Checklist
Use this checklist at the scheduled review date or when conditions change significantly.
- ☐ Has the original context changed? (Market shift, new data, team restructure, budget change)
- ☐ Are the original constraints still valid? (Technical limitations, legal requirements, resource availability)
- ☐ Have the rejected alternatives become more viable? (New tooling, reduced cost, changed requirements)
- ☐ Is the decision producing the expected outcomes? (Check the metrics or goals cited in the rationale)
- ☐ Are there unintended consequences that were not anticipated? (Technical debt, customer complaints, team friction)
- ☐ Does the decision still align with the current product strategy and company goals?
- ☐ Verdict. Reaffirm / Modify / Reverse / Extend review period
Filled Example: Platform Migration Decisions
Context. A platform engineering team at a Series C SaaS company ($25M ARR, 80 engineers) is migrating from a monolithic Rails application to a microservices architecture. The PM for the platform team logged the following decisions over 3 months to maintain alignment across engineering, product, and leadership.
Decision Log (Example)
| Decision ID | Date | Decision | Context | Alternatives Considered | Rationale | Decision Maker | Stakeholders Consulted | Status | Review Date |
|---|---|---|---|---|---|---|---|---|---|
| D-014 | 2026-01-08 | Adopt the Strangler Fig pattern for monolith migration instead of a full rewrite. | Engineering estimated a full rewrite at 18 months. Product cannot freeze feature development for that long. We need an incremental approach that allows feature work to continue during migration. | Full rewrite (18 months, feature freeze), Big Bang cutover (high risk, 6 months), Strangler Fig (incremental, 12 months) | Strangler Fig allows us to migrate one service at a time while the monolith continues to serve production traffic. Lower risk than a full rewrite. Feature teams can continue shipping during migration. Martin Fowler's documentation and our principal engineer's experience at her previous company confirmed this approach for our scale. | Sarah (VP Engineering) | Alex (PM, Platform), James (CTO), 4 Engineering Leads | Active | 2026-07-08 |
| D-015 | 2026-01-15 | Use gRPC for inter-service communication instead of REST or message queues. | Our microservices will need synchronous request/response for most interactions. Latency budget is <50ms for internal calls. We have 3 engineers with gRPC experience. | REST (simple, universal), gRPC (fast, typed), Message queues (async, decoupled) | gRPC provides strict typing via Protocol Buffers (catches integration bugs at compile time), lower latency than REST for internal calls, and built-in streaming for our real-time data pipeline. REST was rejected because we need type safety across 15+ planned services. Message queues were rejected for synchronous call paths but will be used alongside gRPC for async workflows. | James (CTO) | Sarah (VP Eng), Alex (PM), 4 Engineering Leads | Active | 2026-07-15 |
| D-016 | 2026-01-22 | Start migration with the billing service (not the user service). | Need to pick the first service to extract. Billing and User are the two most independent modules in the monolith. | User service first (simpler data model, fewer dependencies), Billing service first (higher business value, more complex), Notifications service first (lowest risk, least value) | Billing service has the highest standalone business value: it enables independent scaling during month-end invoice runs that currently slow the entire monolith. The billing team (2 engineers) is the most experienced with microservices patterns. User service will be second. Notifications service is too low-value to justify the migration overhead as a first project. | Alex (PM, Platform) | Sarah (VP Eng), Billing team lead, Finance team lead | Active | None |
| D-017 | 2026-02-05 | Use AWS ECS Fargate for container orchestration instead of self-managed Kubernetes. | Our DevOps team is 2 people. Kubernetes operational overhead is significant. We need container orchestration but cannot afford a dedicated platform team. | Self-managed Kubernetes (flexible, complex), AWS EKS (managed K8s, moderate complexity), AWS ECS Fargate (serverless containers, simple) | ECS Fargate eliminates cluster management entirely. Our 2-person DevOps team cannot support Kubernetes on-call rotations alongside migration work. Cost is 20-30% higher than self-managed K8s but the operational savings justify it at our current team size. We will reassess when we reach 10+ services or if DevOps headcount grows to 5+. | James (CTO) | DevOps team (2), Sarah (VP Eng), CFO (for cost approval) | Active | 2026-08-05 |
| D-018 | 2026-02-12 | Maintain a shared PostgreSQL database during Phase 1 instead of database-per-service. | Microservices best practice calls for database-per-service, but splitting the database during the same phase as the service extraction doubles the migration scope and risk. | Database-per-service immediately (clean architecture, high risk), Shared database Phase 1 then split Phase 2 (pragmatic, moderate risk), Keep shared database permanently (lowest effort, highest coupling risk) | Shared database in Phase 1 limits the blast radius of the first service extraction. We extract the billing service code into its own container first, prove the deployment pipeline works, and then split the database in Phase 2. This avoids the dual migration risk. The tradeoff is temporary coupling. Marked for mandatory review at Phase 2 kickoff. | Alex (PM, Platform) | James (CTO), Billing team lead, Database admin | Active | 2026-05-01 |
Expanded Entry Example (D-014)
Decision ID. D-014
Date. 2026-01-08
Decision. Adopt the Strangler Fig pattern for monolith-to-microservices migration.
Context.
The monolithic Rails application is approaching performance limits during peak traffic periods. Month-end billing runs cause 30-40% latency degradation across all services because the monolith shares a single application server pool. Feature development velocity has slowed because all teams deploy from the same codebase: a regression in the billing module delayed a growth team feature by 2 weeks last quarter.
Engineering leadership proposed a migration to microservices. The PM (Platform) was tasked with recommending an approach that balances migration progress with continued feature delivery. Product leadership made it clear that a complete feature freeze longer than 4 weeks was not acceptable given Q1 growth targets.
Alternatives Considered.
| Option | Description | Pros | Cons |
|---|---|---|---|
| A. Strangler Fig (Chosen) | Incrementally extract services from the monolith. Route traffic to new services via API gateway. Decommission monolith modules as they are replaced. | No feature freeze. Lower risk per increment. Allows learning from each extraction. | Longer total timeline (12 months). Temporary complexity of running both systems. Requires API gateway investment. |
| B. Full Rewrite | Rebuild the entire application as microservices from scratch. Cut over when complete. | Clean architecture. No legacy constraints. | 18-month timeline. Requires feature freeze or dual-track development. High risk of scope creep. Team estimated 40% chance of missing the 18-month target. |
| C. Big Bang Cutover | Extract all services in parallel, then switch traffic all at once. | Faster than Strangler Fig on paper (6 months). No hybrid period. | Highest risk. A single service failure blocks the entire cutover. No fallback if the new system has issues. Team unanimously rejected this option. |
Rationale.
Strangler Fig was chosen because it is the only approach that allows feature development to continue during migration. The 12-month timeline is 6 months shorter than the full rewrite and carries significantly lower risk than the Big Bang approach. The temporary complexity of running both systems is manageable with proper routing at the API gateway layer. Our principal engineer successfully used this pattern at a similar-scale company (120 engineers, Rails monolith).
Decision Maker. Sarah Chen, VP Engineering
Stakeholders Consulted. Alex (PM, Platform), James (CTO), 4 Engineering Leads (Growth, Billing, Data, Infrastructure), CFO (for budget approval of parallel infrastructure costs)
Risks and Mitigations.
- Hybrid system complexity increases debugging difficulty. Mitigation: invest in distributed tracing (Datadog APM) before extracting the first service.
- Migration timeline may extend beyond 12 months as new requirements emerge. Mitigation: scope each extraction as an independent project with its own deadline. Slip on one service does not block others.
- Feature teams may resist working in the hybrid architecture. Mitigation: provide clear guidelines for where new code should live (new service vs. monolith) and review in architecture syncs weekly.
Status. Active
Review Date. 2026-07-08 (6-month checkpoint)
Related Decisions. D-016 (first service selection), D-017 (container orchestration), D-018 (database strategy)
Key Takeaways
- Log decisions within 24 hours. Context degrades faster than you expect. A decision entry written the same day takes 10 minutes. Reconstructing the same entry a month later takes 30 minutes and is less accurate.
- Always document the rejected alternatives. This is the field that prevents relitigating the same decision. When someone proposes an approach you already considered and rejected, point them to the log entry.
- Use the four status levels (Active, Superseded, Reversed, Under Review) to keep the log current. A decision log full of stale entries that nobody maintains is worse than no log at all.
- Set review dates for reversible decisions. Product strategy changes. Technical constraints evolve. A decision that made sense in January may need revisiting by July. The review checklist in this template gives you a structured way to reassess. For more on building a strategic decision-making practice, see the Product Strategy Handbook.
- Keep the log in a shared, searchable location. If the decision log is buried in a folder that only the PM accesses, it will not serve its purpose. Put it where your engineering leads, designers, and stakeholders can find it and reference it independently. Use the product review meeting to surface key decisions and ensure stakeholder alignment.
About This Template
Created by: Tim Adair
Last Updated: 2/19/2026
Version: 1.0.0
License: Free for personal and commercial use