Decision Record Template (Principled ADR format)

Decision Record Template (Principled ADR format)

This template helps teams capture decisions so they are discoverable, actionable, and useful for future learning. Use a lightweight record for quick, low‑impact choices and a formal record for high‑impact or cross‑organizational decisions. The template focuses on clear trade‑offs, assumptions, evidence, ownership, and measurable outcomes rather than bureaucratic detail.

When to create a record

• Lightweight record: quick decisions that affect a single team or sprint, or when immediacy matters and the expected impact is small.
• Formal record: decisions that are cross‑team, high cost, regulatory, long‑lived, change architecture or core processes, or will be hard to reverse.
• Create a record whenever clarifying who owns follow‑through, what will be measured, or what assumptions must be tested.

Template fields (copy and adapt)

1. Decision ID — short stable identifier (e.g., DEC-2026-014)
2. Title — one concise descriptive sentence
3. Date — creation date
4. Context / Trigger — what prompted the decision, relevant background, and who is affected
5. Decision Type — choose: Technical, Process, Policy, Vendor, Product, Safety, Compliance, Other
6. Options Considered — list alternatives (short bullets) with key pros/cons for each
7. Chosen Option — what you decided (be explicit)
8. Rationale & Trade‑offs — why this option was chosen; state the trade‑offs and the primary reasons that mattered
9. Evidence & Data — direct evidence, experiments, benchmarks, references, and links to datasets or analysis
10. Key Assumptions — list assumptions that, if false, would change the decision
11. Expected Impact / Success Criteria — measurable indicators to validate the decision (metrics, target ranges, timelines)
12. Risks & Mitigations — known risks and the plan to reduce or monitor them
13. Dependencies — other teams, systems, approvals, or resources required
14. Owner / Responsible Party — person or team accountable for implementation and follow‑up
15. Review Date / Checkpoint — when the decision will be revisited (date or condition)
16. Status — Planned / In Progress / Implemented / Reversed / Deprecated
17. Outcome / Post‑mortem Notes — updated after the review: what happened vs expectations, lessons learned, next steps
18. Links & Artifacts — links to tickets, documents, diagrams, datasets, test runs
19. Classification & Privacy — public, internal, restricted; do not store sensitive personal data in the record
20. Retention — recommended retention period and archival location

How to write a useful rationale

• Start with the core reason: what critical outcome were you optimizing for?
• State the main trade‑offs in plain language (cost vs speed, reliability vs flexibility, privacy vs personalization).
• Avoid long narratives—use bullets and evidence links so future readers can scan quickly.
• Call out any assumptions explicitly so they can be tested later.

Lightweight vs Formal: practical guidance

Follow‑up and learning process

1. Owner adds initial evidence and success criteria at creation time.
2. At the Review Date, owner records Outcome / Post‑mortem Notes: what actually happened, metric outcomes, and whether assumptions held.
3. If outcomes are negative or assumptions failed, capture corrective actions and update the record's Status.
4. Periodically (quarterly or per domain cadence) scan recent decision records to surface cross‑cutting lessons and process improvements.

Common mistakes to avoid

• Treating the record as a checkbox—no follow‑up or measurement.
• Overloading records with sensitive personal data or irrelevant operational logs.
• Leaving the record orphaned—no owner, no review date, or unclear scope.
• Writing vague rationales that hide the trade‑offs; this prevents learning.

Sample (lightweight) record

Decision ID: DEC-2026-042

Title: Use Managed DB Service for New Reporting Pipeline

Date: 2026-07-14

Context: Reporting pipeline needs stable storage for daily aggregates. Team capacity to run DB operations is limited.

Chosen Option: Use Managed DB Service (vendor X)

Rationale: Lower operational burden and faster time to market; trade‑off is higher OPEX and vendor lock‑in.

Assumptions: Managed service uptime SLA ≥ 99.9%; data egress costs within budget.

Owner: Data Platform Team

Review Date: 2026-10-01 (evaluate costs and SLA experience)

Links: ticket-1234, cost-analysis-v1

Sample (formal) record outline

For formal records include structured sections for: stakeholder endorsements, regulatory considerations, full options matrix (scored), projected TCO, migration plan, rollback criteria, testing plan, and an explicit measurement dashboard that the owner will update.

Privacy & retention notes

• Do not include confidential personal health, payroll, or other sensitive PII in the record body. Instead, link to secure documents when necessary and classify the record appropriately.
• Recommended retention: keep operational decisions that affect architecture, compliance, or safety for at least 3–7 years depending on regulatory requirements; archive or summarize outdated low‑value records.

Tags and discoverability

Add tags such as team, domain, impact (low/medium/high), technology, and year to make records searchable and useful for pattern discovery.

Minimum quality checklist before saving

• Is the owner clearly named?
• Is there at least one measurable success criterion?
• Is a review date scheduled?
• Are key assumptions listed?
• Are links to evidence or tickets provided?

Integration & reuse suggestions

Store decision records in a central registry with consistent metadata to support searches, dashboards, and retroactive analysis. Consider linking records to project boards, compliance systems, and knowledge collections so they feed learning workflows.