Decision Records

Decision Records — Freeze the Why Before It Evaporates

A consequential choice got made. Capture it as one short, immutable, numbered ADR: the context that forced it, the real options weighed, the decision, and what it costs you both ways. Six months from now this file is the only thing standing between you and re-litigating the whole thing.

You own the durable single-decision artifact — an Architecture/Any Decision Record (ADR). Not a meeting recap, not a runbook, not a spec. One bounded choice, recorded so the reasoning survives the people who made it.

The one test: is this even ADR-worthy?

Write an ADR iff the choice is costly to reverse OR future-you will ask "why did we do it this way". Everything else is noise — an ADR for a trivial reversible tweak is just paperwork, and ADRs lose all their value the moment they become forced ceremony (this is the consistent message from Fowler and the AWS Architecture Blog).

If you can rip it out in an afternoon and nobody will ever ask why, don't write an ADR. Decide, move on.

Decide home + naming once

Pick a storage convention before the first record, and never spawn a competing second log. Default to the project's existing convention if one exists.

Prefer numeric-prefix: NNNN-title-with-dashes.md. Stable IDs are what make "Superseded by ADR-0012" mean something.

Where to store (first match wins):

1. The project's existing convention — never invent a parallel log.
2. A code repo with no convention: docs/adr/ (also seen as doc/adr/).
3. A harness workspace: 02-DOCS/wiki/decisions/, indexed in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a short pointer).

textCopy code
Bad:  decision-final-v2-REAL.md          # no ID, no order, will rot
Bad:  notes/adr/db.md                     # buried, not in the log
Good: docs/adr/0007-choose-postgres.md    # stable ID, sorts, cross-referencable

Seed the index the moment you create the first ADR — a README row or 0000-index.md listing id, title, status, date. An ADR that isn't in the index is an orphan nobody will find.

The record spine

Map every ADR to the MADR 4.0.0 template (released 2024-09-17 — the current version). MADR ships full and minimal variants; use minimal until a section earns its place.

Required spine, in order: Title → Status → Date → Context and Problem Statement → Decision Drivers → Considered Options → Decision Outcome → Consequences. The MADR-optional sections (Confirmation, Pros and Cons of the Options, More Information) you add only when they pull weight.

Minimal skeleton — this is enough for most decisions. When the ADR lives in a harness workspace (02-DOCS/wiki/decisions/), it is part of an OKF v0.1 bundle, so it opens with YAML frontmatter carrying a non-empty type: decision (plus the OKF-recommended title/tags/ timestamp). The body keeps the human-readable - Status:/- Date: lines verbatim — they are the decision's domain record and scripts/verify.sh reads them, so the frontmatter is purely additive. Cross-references use standard markdown links, never wikilinks. (In a plain code repo under docs/adr/, the frontmatter is optional — OKF conformance only governs the wiki bundle.)

markdownCopy code
---
type: decision
title: "Choose Postgres over DynamoDB for the primary store"
tags: [adr, database, billing]
timestamp: 2026-06-02T00:00:00Z
---

# 7. Choose Postgres over DynamoDB for the primary store

- Status: accepted
- Date: 2026-06-02
- Deciders: @alice, @bob

## Context and Problem Statement

We need a primary datastore for the billing service. Relational
invoicing data, ~2k writes/min, team of 3 with deep SQL experience,
EU data-residency required. Which store do we adopt?

## Decision Drivers

- Strong relational integrity for invoices (foreign keys, transactions)
- Team SQL fluency; near-zero NoSQL operational experience
- EU residency + self-host option (constitution §data-residency)

## Considered Options

- Postgres (managed, EU region)
- DynamoDB
- MongoDB Atlas

## Decision Outcome

Chosen: **Postgres**, because it matches the relational shape of the
data and the team's existing fluency, with the lowest operational risk.

## Consequences

- Good: ACID transactions, mature tooling, team productive day one.
- Bad: we own connection-pool and vertical-scaling concerns earlier.
- Follow-up: provision read replica before launch (ADR-0009 tracks scaling).

Keep it to 1–2 pages, readable in 5–10 minutes. If a record sprawls, you're probably bundling two decisions — split them. The full annotated MADR full+minimal templates and a worked example live in references/templates.md.

Write context that forces the decision

The context section must make the decision feel inevitable. State the problem and the constraints — not the solution.

• State the problem, not the answer. "We need to pick a store" not "We should use Postgres." The verdict belongs in Decision Outcome.
• Quantify. "~2k writes/min", "team of 3", "EU residency", "p99 < 100ms". Numbers are what let future readers judge if your constraints still hold.
• Cite the driver. If a constitution principle or a spec/plan fork forced this, link it. An ADR is often downstream of constitution and cites it as a driver.

markdownCopy code
Bad context:  "We decided to use Postgres because it's reliable."
              (conclusion smuggled in, no constraints, unfalsifiable)

Good context: "Billing needs relational integrity for invoices,
              ~2k writes/min, a 3-person team with SQL but no NoSQL
              ops experience, and EU data residency (constitution
              §data-residency). Which primary store do we adopt?"

Options must be real and comparable

The rejected options are the asset — they're the proof you thought, and they stop the next person re-proposing them.

• List ≥2 genuine options. A single foregone "option" is theatre. If there was really only one path, you don't need an ADR.
• Score each against the same drivers. Apples to apples, or the comparison is meaningless.
• Record why each loser lost. That sentence is worth more than the winner's praise.

markdownCopy code
| Option    | Relational integrity | Team fluency | EU self-host | Op. risk |
|-----------|----------------------|--------------|--------------|----------|
| Postgres  | native               | high         | yes          | low      |
| DynamoDB  | app-enforced         | none         | no (AWS)     | high     |
| Mongo     | partial              | medium       | yes          | medium   |

Consequences, both directions

A one-sided ADR is marketing, and marketing erodes the trust that makes the log worth reading. Record:

• What improves — the upside you bought.
• What degrades — the price you paid, honestly.
• New work / risk it creates — what you now own that you didn't before.
• Follow-ups — concrete tasks, ideally linked to a tracker or a future ADR.

If you can't name a single downside, you haven't finished thinking. Every real choice has a cost.

Status lifecycle + immutability

An accepted or rejected ADR is immutable. You never edit the decision — you write a new ADR that supersedes it and flip the old one's status. This is the whole point: history stays intact.

The supersession ritual (never skip a step):

1. Write the new ADR (e.g. 0012-adopt-trpc.md), status accepted, with a "Supersedes ADR-0004" note in its context.
2. Edit only the status line of the old ADR (0004) to superseded by ADR-0012. Leave its decision and rationale untouched.
3. Back-link both ways so a reader landing on either finds the other.

Never delete an ADR and never rewrite its decision — a wrong-in-hindsight ADR is still true history. A worked supersession pair is in references/templates.md.

Maintain the log

A decision log is only useful if it stays navigable.

• Index every ADR at creation. One row: | 0007 | Choose Postgres | accepted | 2026-06-02 |. No orphans.
• Keep supersession links live in both directions.
• Review cadence. Periodically sweep accepted ADRs — anything reality has overtaken gets a superseding record, not a silent edit.
• Index the log from the entry point — 02-DOCS/wiki/index.md — so onboarding finds it. The broader wiki and onboarding doc belong to knowledge-ops and codebase-onboarding; this skill owns only the ADRs the wiki links to. The meeting that spawned a decision routes to meeting-notes; the repeatable how-to it implies routes to sop-builder.

Anti-patterns

Verify

Lint a produced ADR (or a whole decisions dir) with scripts/verify.sh <path>: it checks for a recognized status, a date, the required sections, ≥2 options, and a valid filename — read-only, no network. It expects the skeletons above.