Decision records

The only place technology may be named — the specification says what the system does, decision records say by what means, and only where it is expensive to reverse.

A decision record exists for what is expensive to reverse. It is the only place in the design documentation where technology may be named: the module reference says what the system does, decision records say by what means.

What earns one

Ask: if this turns out wrong in eighteen months, what does undoing it cost?

Earns a record: persistence, file storage, authentication and directory integration, the authorisation engine, the process engine, notification channel and provider, hosting and data residency, identifier generation.

Does not: anything replaceable behind an interface you own, library choices with no data footprint, formatting and tooling.

The signal is data footprint, not price. A choice that shapes what is stored is expensive to reverse even when the library was free. A choice that only shapes how code is written is cheap to reverse even when the vendor is not.

The shape

# NNNN — Title

**Status:** Proposed | Accepted | Superseded by NNNN
**Date:** YYYY-MM-DD
**Requirements served:** ARC-012, DOM-020

## Context
What forces the decision now. Real constraints, not preferences.

## Options
Each with its honest upside AND what goes wrong later.

## Decision
The option taken, and why the others were not.

## Consequences
What it makes possible, what it closes, what it costs to reverse.

While Proposed, a record is a draft and is edited freely — that is what review is for. Once Accepted, it is never rewritten. When the decision changes, create a new one and mark the old Superseded by NNNN.

Records are numbered because 0003 is the decision's name for ever. They live in docs/decisions/ — see the repository shape.

Writing the options honestly

Every option gets a genuine upside. An option written only to be rejected is a straw man, and it poisons the recommendation that follows. Name the option that is genuinely easiest to build even when you are about to argue against it.

Every option gets what goes wrong later. Including the one you are recommending. A decision record whose recommended option has no downside is a decision record nobody will trust in two years, when the downside arrives.

Cite what you checked, and when. Adoption figures, publication dates, governance status — all move. Date the observation and label it supporting evidence, not a decision criterion. Sustained maintenance matters; a popularity number on a given Tuesday does not.

Traps

Naming a technology in the specification. If a specification sentence names a library, the specification is now false in a different technology. Move it to a record and leave a requirement behind.

Deciding before the behaviour is known. A record that fixes a persistence technology before anyone has written what must be persisted is a guess with a template around it. Write the rules first.

Recording a decision nobody made. If the option was never really in question, you are writing documentation, not a decision. Skip it.

Forgetting the boundary between the artefact and the data. A versioned, immutable artefact — a published process definition — must never embed an identifier of something administered at runtime. It refers to a function or a type; the concrete instance is resolved when the act happens. Otherwise every retirement breaks a frozen dependency and every reorganisation becomes a migration.

Records travel in pairs

Some decisions are only comprehensible together — the process engine and the authorisation model, the storage and the retention rule. Write them as a pair, cross-reference them in their opening lines, and review them together.

Where they interact, say which one owns the interaction. Two records each politely deferring to the other is how a contradiction survives review.

Before it is accepted

Run the record past an independent reviewer — ideally a different model, given the repository facts it needs to check your premises rather than merely agree with your conclusion. Ask specifically for:

the strongest argument against the recommendation
the option that was framed as a straw man
the option that was not considered
whether an industry standard already solves this
what is expensive to reverse

Fold in what survives. Say where the reviewer changed the decision, and say plainly where you disagree with it and why. A reviewer's verdict is input, never a rubber stamp. See the second opinion.