Templates

The seven durable-document shapes we use. Copy → paste → fill. Templates encode owner / review / status fields automatically.

The seven templates

Template	When to use it	Lifespan
Decision Record (ADR)	A choice that constrains the future (tech, vendor, architecture)	Forever — never deleted, only marked deprecated
RFC / Design Doc	A non-trivial change being proposed before implementation	Until implemented, then archived
Runbook	Step-by-step procedure for an operational task	Forever, reviewed monthly
Incident Postmortem	After a customer-facing or production incident	Forever, indexed in Incidents
Sprint Retrospective	Agile ceremony	1 year, then archived
Project Spec	Scoping a multi-week initiative	Until project ships, then archived
Meeting Notes	Only for meetings that produce decisions	6 months, then archived

Template — Decision Record (ADR)

# [ADR-NNNN] [Short imperative title — e.g. "Adopt Drizzle ORM for all DB access"]

| Field | Value |
| --- | --- |
| Status | Proposed / Accepted / Deprecated / Superseded by [ADR-XXXX] |
| Date | YYYY-MM-DD |
| Decider(s) | @Name |
| Stakeholders consulted | @Name1, @Name2 |
| Related ADRs | ADR-XXXX |

## Context
What's the situation that forces this decision? What constraints exist? Why now, not later?

## Decision
The choice, stated as an imperative sentence.

## Why
Reasoning. The trade-offs and constraints that made this the right call.

## Alternatives rejected
Alternative A — why not.
Alternative B — why not.

## Consequences
What becomes easier? What becomes harder? Any migration / cleanup needed?

Template — RFC / Design Doc

# [RFC-NNNN] [Title — what you're proposing]

| Field | Value |
| --- | --- |
| Status | Draft / Approved / Implemented / Withdrawn |
| Author | @Name |
| Reviewers (required) | @Name1, @Name2 |
| Created | YYYY-MM-DD |
| Target ship date | YYYY-MM-DD |
| Jira epic / PR | LINK |

## TL;DR (one paragraph)
What we're proposing, why now, and the single most important consequence.

## Problem
What problem does this solve? Who has it? How big is it?

## Proposed solution
The design.

## Alternatives considered
What else did you consider? Why is the proposed solution better?

## Risks & open questions
What could go wrong? What's unresolved?

Template — Runbook

# Runbook — [Procedure Name]

| Field | Value |
| --- | --- |
| Severity it applies to | P0 / P1 / P2 |
| Owner | @Name |
| Last verified working | YYYY-MM-DD |
| Estimated time | XX minutes |
| Required access | Railway / Neon / GitHub / etc. |

## When to use this runbook
A 1–2 sentence trigger.

## Steps
1. ...
2. ...

## Rollback / safety
How to undo if step N fails.

## After-action
- Verify customer-facing X
- Update incident in [Incidents](/engineering/incidents/)

Template — Incident Postmortem

# Postmortem — [Incident name, dated YYYY-MM-DD]

| Field | Value |
| --- | --- |
| Severity | SEV-1 / SEV-2 / SEV-3 |
| Date | YYYY-MM-DD |
| Duration | HH:MM |
| Incident commander | @Name |
| FM ID | FM-NNN |

> Blameless rule. This document is about systems, not people.

## TL;DR
One paragraph.

## Customer impact
Who, how, severity, duration, detection.

## Timeline (UTC)
| Time | Event |

## Root cause
5 whys.

## Detection
TTD, what earlier signal we missed.

## What is being done
Action items table.

## Lessons learned

Template — Project Spec, Meeting Notes, Sprint Retrospective

(See Confluence template pages or copy from existing ADRs / RFCs in this repo.)

How to use a template

1. Copy the relevant block above into a new MDX file
2. Move the file to the right folder (engineering/adrs/, engineering/incidents/, etc.)
3. Fill in every [bracketed placeholder]
4. Set frontmatter (title, description, audience, status, owner, last-reviewed)
5. Apply labels / link from the parent MOC

Why we have templates at all

OpenAI, Anthropic, and Stripe all use templates aggressively. Three reasons:

1. Shape consistency = search works (filter by type-adr, find all ADRs)
2. Required fields = no orphan pages with no owner
3. Lower friction = people actually write durable docs instead of just talking

A template is a contract: if you use the ADR template, future-you (and your replacement) know exactly where to find “what did we decide” and “what alternatives did we consider.”

Worked examples

For real examples of each template in use:

• ADRs: See Decision Log — 5 published (Drizzle, Repository Pattern, CI Runners, Page Layout, Apex Models)
• Runbooks: See Runbooks — 3 published (Incident Response, DB Migration, CI Pipeline)
• Postmortems: See FM-032 exemplar
• App Catalog reference pages: See App Catalog — 14 app reference docs

Related

• How We Use This Wiki
• Engineering ADRs
• Engineering Incidents