Decision Records

A decision record states one choice that is expensive to reverse, with the options weighed and the evidence cited.

Intent#

A decision record states one choice that is expensive to reverse, with the options weighed and the evidence cited. This page states where the record lives, what it holds, and how it ends.

Reference#

Where a record lives#

Item	Value
Path	`docs/product/decisions/<number>-<name>.md` in the consumer repository
Template	`templates/consumer/decision.md`
Metadata type	`decision`

Identifier form#

The identifier is decision/<number>-<name>, such as decision/0047-extend-loan-period. The number counts as a word toward the six-word name bound. The name states the choice in words. The number keeps proposal order only.

What a record contains#

Section	What it states
Context	The concrete constraint or conflict forcing a choice.
Options	Each option weighed, with its cost.
Decision	The selected behavior and its decider.
Consequences	The required work and the accepted cost.
Evidence	The research and constraints the choice rests on.

The record also carries decided with the approval date and changeWhen with what would change it. It carries options with the weighed options, decides with the records it sets, and basedOn with the constraints and research behind it.

Replaced, never edited#

An approved record never changes. A later choice is a new record naming the old one in replaces. The old record stands retired beside the new one. A departure from a shared standard is an exception record rather than a decision.

The draft gate#

A record stays unapproved while a decision behind it stays draft. Approval names the decider in decidedBy and the date in decided.

Notes#

The outside conventions for this artifact are Nygard's architecture decision record and MADR. Both record context, decision, and consequences in one immutable file per choice, and this record keeps that shape.