Write the decision down, or it didn't happen

Why this rule exists

A decision that lives only in someone's memory isn't a decision, it's a rumor with a half-life. Three months later nobody can remember whether we chose Postgres because of a real constraint or because someone had a bad week with the alternative, and the reasoning that would let us revisit it sensibly is simply gone. Writing it down, the decision, the date, who made it, and crucially why, turns a moment of judgment into a durable artifact the team can build on and argue with. It protects us from relitigating the same question every quarter, and it protects the decider from being second-guessed by people who never saw the constraints they were working under. It's also how new people absorb why the system is the way it is, instead of assuming everything that looks odd is a mistake. The written record is the difference between a team that accumulates wisdom and one that just accumulates code. If it's not written down, it didn't happen, and we'll pay for it later in a meeting we could have skipped.

In practice

For any decision that's expensive to reverse or affects more than one person, write a short decision record before you consider it settled. Capture the context, the options you weighed, the choice, and the reasoning, in a few paragraphs, not a dissertation. Note who owns the decision and the date, so future readers can weigh how stale it is. Put it somewhere durable and findable, linked from the relevant project, not buried in a chat scroll. Record the decision even when it's unanimous and obvious, because obvious-in-the-moment is exactly what gets forgotten. When you later change your mind, don't delete the old record, write a new one that supersedes it and says why, so the trail of reasoning stays intact.

Example

# Use Postgres for the primary store
Date: 2026-06-09  ·  Owner: Priya  ·  Status: accepted

## Context
We need a primary datastore for the billing service.
Team already runs Postgres; low ops appetite.

## Options considered
- Postgres — known, relational, boring (good)
- DynamoDB — scales, but access patterns still fluid
- SQLite — too limited for concurrent writes here

## Decision
Postgres. Familiarity and relational integrity outweigh
theoretical scale we don't yet have.

## Consequences
Accept vertical-scaling ceiling for now; revisit if
write volume 10x's. Supersede this doc if so.

When it doesn't apply

Small, easily reversed decisions don't need a formal record; deciding what to name a variable or which morning to ship is not a constitutional matter. The bar is roughly: would someone reasonably ask 'why did we do it this way?' six months from now. If yes, write it down.

Related rules in this book

Sources

• The GitLab Handbook — GitLab Inc., ongoing — the definitive public example of a handbook-first, write-it-down, async-default operating model, and a direct influence on our decision-record and open-by-default rules.
• The Manager's Path — Fournier, Camille. O'Reilly, 2017 — on clear ownership, decision-making, and why writing things down is how teams scale their judgment.