ADRs: the fifteen-minute record for one decision

September 17, 2026

The win for today: a docs/adr/ directory in the DocuDex repo with two records in it — the storage decision and the manifest decision — and two rows in the ADR index in career/notes.org. About thirty-five minutes. Both decisions are already argued in your design doc, so this is compression, not new thinking.

Key idea —

A design doc covers a system. An ADR covers one decision — the kind a future engineer would otherwise ask "why on earth?" about — and it is never deleted. Reverse it by writing a new one and marking the old one superseded, so the history of what you believed stays readable.

1. Nygard's five sections (5 min)

Michael Nygard's 2011 post Documenting Architecture Decisions is the origin of the format and still the best description of it. The reference sheet has the full table; the shape is:

Title — "short noun phrases". Name the decision, not the problem: Store docs as Markdown with a SQLite index, not Storage.

Context — "the forces at play, including technological, political, social, and project local", in value-neutral language. A stranger should be able to read the context and not yet know which way you went.

Decision — "our response to these forces", in active voice: "We will…". One paragraph, stated against what it was chosen over.

Status — proposed until agreed, then accepted; later deprecated or superseded by NNNN.

Consequences — "the resulting context, after applying the decision. All consequences should be listed here, not just the 'positive' ones." This is the section people skimp on, and the one a future reader needs most.

Length: "one or two pages". Nygard wants prose "as if it is a conversation with a future developer" and is blunt about bullets: "acceptable only for visual style, not as an excuse for writing sentence fragments". Files live in the repo, numbered sequentially, numbers never reused; a reversed decision is kept "but mark it as superseded".

2. Design doc, ADR, or neither? (5 min)

All of these are real DocuDex decisions or could be. Sort them.

Where does it go?0 of 7

Use modernc.org/sqlite rather than mattn/go-sqlite3

How DocuDex fetches, stores and serves docs, end to end

Rename the `lookup` command to `find`

Derive a manifest from go.mod rather than reading go.mod directly

Add keyboard shortcuts to the web app

Six months in: drop the local server and ship a static site after all

Markdown on disk is the source of truth; SQLite is a rebuildable index

3. Consequences, all of them (4 min)

The storage decision, consequences section only.

Positive only

Humans get full-text search in the web app and agents can cat and grep the docs directly. Distribution stays a single binary with no C toolchain.

All consequences

Humans get full-text search in the web app and agents can cat and grep the docs directly. Distribution stays a single binary; contributors need no C toolchain. Because the Markdown files are the source of truth, the SQLite file is a cache: sync must rebuild it, and it can be deleted safely. There are now two read paths to keep consistent in tests. modernc.org/sqlite is slower than the cgo driver, so a large add will be noticeably slow; we need a benchmark on a real monorepo before calling that acceptable.

Same decision. The second version tells the future developer what they will run into — and turns the 'sync cost' from your design doc into a concrete obligation on sync.

4. Do it (20 min)

In the DocuDex repo (create it if it does not exist yet — the ADRs can be the first commit):

Make docs/adr/ and a README.md in it with a three-column table: number, title, status.
Write 0001-store-docs-as-markdown-with-a-sqlite-index.md. Lift the context from your design doc's storage paragraph and the storage entry in Alternatives — but strip every opinion out of the context; it should read the same whichever way you had decided. Decision in one "We will…" paragraph, naming what it beat. Consequences: at least one thing that got harder. Status: accepted.
Write 0002-derive-a-manifest-from-go-mod.md the same way. This one has a real rejected alternative (read go.mod directly) and real consequences (drift detection is now your problem; sync is explicit).
Add both rows to the ADR index table in career/notes.org — the format there is date, project, ADR, decision in one line, link. Try writing the one-line decision as a Y-statement: "In the context of X, facing Y, we decided Z to achieve A, accepting B."

Time-box each ADR to fifteen minutes. If it is taking longer, you are re-deciding rather than recording.

Self-review: each ADR0 of 7

Is the title a noun phrase naming the decision, not the topic?"Storage" is a topic. "Store docs as Markdown with a SQLite index" is a decision.Could a stranger read the context and not yet know which way you went?Nygard: value-neutral. If the context argues, it is the decision section wearing a disguise.Does the decision say "We will…" and name what it was chosen over?Active voice; the rejected option is what makes it a decision rather than a description.Do the consequences include at least one thing that got harder?"All consequences, not just the positive ones."Is everything about how it works (rather than why it was chosen) back in the design doc?An ADR that explains the implementation will be wrong within a month.Is it under two pages, in sentences rather than fragments?Nygard: a conversation with a future developer.Are both rows in the career/notes.org index?Evidence for the tech-lead scoreboard.

5. Retrieval (2 min)

One of these is from lesson 3.

Q1. Nygard's Consequences section must list:

Q2. When a decision is reversed, the old ADR is:

Q3. Nygard's Decision section is written:

Q4. A design paragraph without a cost is: