Canonical Decision Record Template

Canonical Decision Record

Use this template to make important decisions visible, traceable, and productive. A short, consistent decision record preserves context, makes assumptions explicit, helps teams learn from outcomes, and reduces repeated debates. Treat the template as a starting point—adapt fields and labels to match your team's language and governance.

When to use this record

• Decisions that affect more than one person, team, or system
• Long-lived decisions or architectural, policy, budget, or vendor choices
• Decisions you want to revisit, measure, or convert into experiments
• When you need a clear owner and a plan for follow-up learning

How to use

Keep each record short and focused. Capture the minimum useful detail to understand why the decision was made and how success will be measured. Link to supporting artifacts (design docs, tickets, data) rather than pasting everything. Assign a decider and one or two stakeholders. Add a version or change history when the decision is revisited.

Template fields (copy and adapt)

1. Decision title

   A concise name that will appear in indexes and search results. Example: "Adopt centralized feature-flag service".

2. Date

   Date the decision was recorded (and version dates for updates).

3. Decider

   Person or role accountable for making the call (not necessarily the implementer). Use role if the exact person may change.

4. Stakeholders

   Teams, roles, or individuals materially affected by the decision. Include those who should be consulted or informed.

5. Problem statement

   One to three clear sentences describing the problem or opportunity the decision addresses. Focus on outcomes, constraints, and why current state is insufficient.

6. Options considered

   List the realistic alternatives and short pros/cons for each. If you ran a quick analysis or pilot, link results here.

7. Decision rationale

   The chosen option and why. Include the main reasons that tipped the balance (cost, risk, speed, customer impact, strategic fit).

8. Key assumptions

   Assumptions you are making that, if false, would change the decision. Make them explicit so follow-up experiments can test them.

9. Success criteria

   Concrete, measurable signals you will use to decide if the choice is working (metrics, qualitative feedback, deadlines).

10. Follow-up experiments / actions

    Short experiments, monitoring tasks, or milestones to validate assumptions and measure success. Assign owners and dates.

11. Retrospective notes / outcomes

    After the decision has been exercised, record what happened, what you learned, and whether the original decision should be kept, adapted, or reversed.

12. Links and references

    Links to design docs, tickets, data sources, meeting notes, prototypes, or vendor pages.

Sample completed example (short)

Decision title: Adopt centralized feature-flag service
Date: 2026-04-12
Decider: Head of Engineering (role)
Stakeholders: Platform, Product, QA
Problem statement: Teams are building inconsistent feature-flag solutions that increase rollout risk and maintenance cost.
Options considered: 1) Continue with team-owned flags (fast now, costly later); 2) Build internal shared service (control, long build time); 3) Adopt managed vendor (faster, recurring cost).
Decision rationale: Choose vendor to accelerate safe rollouts and provide standard SDKs; revisit after 12 months.
Key assumptions: Vendor SDKs meet performance needs; cost fits budget; teams will adopt the standard API.
Success criteria: 80% of teams using central flags within 6 months; reduced rollback incidents by 50%.
Follow-up experiments: Pilot with two teams (owner: Platform Eng, due: 2026-05-15); load test vendor SDK (owner: Ops, due: 2026-04-30).
Retrospective notes: (to be filled after 6 months)
Links: Proposal doc, vendor evaluation matrix, pilot tickets
  

Practical tips and governance

• Keep records short—link to supporting evidence instead of embedding it.
• Use roles rather than names for long-lived accountability (e.g., "Product Owner - Billing").
• Decisions that materially affect customers, compliance, security, or architecture should include at least one cross-functional stakeholder and an explicit rollback plan.
• Tag each record with area/team and decision type (e.g., architecture, vendor, policy) to make the decision log searchable.
• Schedule automatic reminders to review follow-up experiments and add retrospective notes.

Avoid these pitfalls

• Recording without reflecting: capture outcomes and learning, not just the initial choice.
• Over-documenting: lengthy essays discourage use—capture what someone needs to decide or re-evaluate later.
• One-size-fits-all enforcement: treat the template as a guide; adapt for local context and complexity.

Suggested adaptations

Consider adding fields your organization needs such as regulatory risk, budget impact, required approvals, estimated implementation effort, or links to compliance checklists.

Next steps for teams

1. Copy this template into your team space or shared decision log.
2. Complete a record for any cross-cutting or long-lived decision.
3. Assign a decider and plan follow-up experiments with owners and dates.
4. Set a cadence (e.g., quarterly) to review recent decisions and outcomes.