# The Design Decision Record

> One page, four fields. This is what replaces the artifact as proof that
> judgment happened. A file shows what you made. This shows why that one and
> not the eleven others, in a form somebody can act on without you in the room.
> Takes ten minutes to fill. Write it while the decision is still warm.

---

## When to write one

Not for every choice. Write a record when at least one of these is true:

- Somebody will ask "why is it like this" more than once.
- You picked one direction and killed others that were credible.
- The decision constrains what other people can build later.
- You would be annoyed if it got quietly reversed.

If none of those apply, skip it. A record for every button is how the practice
learns to ignore records.

---

## The four fields

### 1. The decision

One sentence, present tense, specific enough to be wrong.

Good: "Suggested replies appear inline under the message, never as a modal, and
never more than three at a time."

Bad: "We improved the suggestion experience." That is a summary, not a decision.
Nobody can disagree with it, which means nobody can check it.

### 2. The constraints that produced it

Two to four rules, each with the failure condition attached. These are the part
that does the work. Written well, a competent stranger or an agent reaches the
same decision without you.

Each constraint follows the shape: **rule, then what breaking it looks like.**

Example: "A suggestion the user can accept in one click has an undo that is
equally cheap. Broken when accepting takes one tap and reversing takes a support
ticket."

### 3. What we gave up

Name the options you killed and the cost of killing them. This field is the one
people skip, and it is the field that makes the record worth reading in six
months.

If you cannot name a real cost, you did not have a real decision. You had a
preference, and preferences do not need records.

### 4. How we will know this was wrong

A signal, with a rough threshold and a date to look. Not a metric dashboard, one
observable thing.

Example: "If more than a handful of users in the next round of sessions try to
edit a suggestion before sending, the three-at-a-time limit is the wrong
constraint and the record gets revised."

A record with no falsifier is an opinion with a template around it.

---

## The template

Copy this block. One decision per file.

```markdown
# DR-000: <short title>

Date:
Owner:
Surface / feature:
Status: proposed | active | superseded by DR-000

## Decision
<one sentence, present tense>

## Constraints that produced it
1. <rule>. Broken when: <failure condition>.
2. <rule>. Broken when: <failure condition>.
3. <rule>. Broken when: <failure condition>.

## What we gave up
- <option killed>: <what it would have bought us>
- <option killed>: <what it would have bought us>

## How we will know this was wrong
<signal>, checked on <date>.
```

---

## A worked example

```markdown
# DR-014: Inline suggestions, maximum three

Date: 2026-03-04
Owner: <name>
Surface: message composer
Status: active

## Decision
Suggested replies appear inline beneath the composer, maximum three, never as a
modal and never auto-selected.

## Constraints that produced it
1. A suggestion never occupies the primary action position. Broken when the
   suggestion is the largest or most emphasized control on the screen.
2. Accepting a suggestion is one action and reversing it is one action. Broken
   when the reverse path requires more taps than the accept path.
3. The composer is usable with suggestions off. Broken when a user who ignores
   every suggestion loses functionality available before the feature shipped.

## What we gave up
- Modal picker with six options: higher acceptance in the first session, at the
  cost of interrupting people who already knew what they wanted to say.
- Auto-selecting the top suggestion: fastest happy path, and the fastest way to
  send a message the user did not write.

## How we will know this was wrong
People editing suggestions before sending, rather than accepting or ignoring
them, means three was too few or the ranking is poor. Checked in the next round
of sessions.
```

---

## Filing rules

Keep them together and keep them boring. One directory, sequential numbers,
never delete. A superseded record stays in place with its status changed and a
pointer to the record that replaced it, because the reasoning behind the
reversal is often more useful than the reversal.

Two habits that decide whether this survives contact with a real team:

- The record gets written by the person who made the call, not by a note-taker.
  Delegating the record is how it turns into meeting minutes.
- The record is linked from wherever the work lives. A record nobody can find
  from the work is a diary entry.

---

## The one thing to do this week

Take a decision you already made and argued for at least twice. Write the record
after the fact. It should take ten minutes, and the field that hurts to fill is
the one telling you the decision was thinner than you remembered.

---

_From "The Receipt and the Work", chapter 2 of The Design Operating Model._
_falkster.com/design/the-receipt-and-the-work_