Decision Records for a Life

The Problem It Solves

Without a written record of why decisions were made, every revisit costs cognitive energy reconstructing context — and across a portfolio that compounds badly. “Why did we decide the brief goes to that app?” “Why is there no central portfolio file?” “Why does this curator get write access and that one doesn’t?” Without the record, each of these becomes a re-litigation, and re-litigations are how good decisions get undone by whoever argues last.

Software teams solve this with Architecture Decision Records. This system applies them to a life.

Anatomy

## ADR-NNN — short title

**Date:** YYYY-MM-DD   **Status:** in effect | superseded by ADR-MMM | reversed
**Context.** What was true, what hurt, what triggered the call.
**Decision.** What was decided, precisely — including alternatives rejected.
**Consequences.** (+) what it buys. (−) what it costs, stated honestly.
**Reverse if:** the observable condition that would make us undo it.
**Related:** ADR-006 · ADR-019

Two conventions give it teeth:

ADR before action. When you make a structural call — create or retire a venture, change a tool default, promote a curator’s write access, set a workflow norm — the assistant appends the record before acting on it. The record is the act of deciding, not documentation after the fact. This also makes the action reviewable: you can read the record in the next brief and say “no, not like that” before anything has been built on it.

“Reverse if” is mandatory. Every decision names its own escape hatch as an observable condition: “if weekly corrections exceed five and are pattern-shaped, narrow the edit zones again.” This is what stops old decisions from calcifying into superstition. Disagreements with the past become checks against a written trigger, not arguments.

What Counts as Structural

A useful test: would a new session, reading only the vault, be surprised by this? If yes, it needs a record. Some examples of records the reference system actually holds, abstracted:

• One hub note per venture; no central portfolio file.
• One task database, labels per venture; four cognitive modes, hard cap.
• The chief of staff holds no credentials; curators do.
• Full edit authority over the vault with four audit rails.
• The daily brief goes to a messaging channel as one message under a hard character cap.
• Curator-drafted tasks default to low priority, with a narrow carve-out for time-sensitive items.
• Activity signal comes from file edits, not task counts.
• Reports delivered as files are HTML, not Markdown, because Markdown reads as plain text on a phone.
• A reply to a message the system sent resumes the session that sent it.
• personal is not a venture label; catch-all captures route by a fixed table.

Some of those are large; some are tiny. What they share is that each changed how every future session behaves, and each has a condition under which it would be undone.

Two Logs, Not One

Cross-portfolio decisions live in the single root Atlas/decisions.md. Venture-internal tactical calls — “we’ll use vendor X for this project”, “the launch moves to Q3” — live in that venture’s own decisions.md. The test is scope: if a decision only makes sense inside one venture folder, it lives there.

Superseding, Not Deleting

Decisions get reversed. When the daily brief’s curator dispatch moved from in-session sub-agents to headless subprocesses and then back again, the log kept both records: the second cites the first, notes which “reverse if” clause fired, and marks the first superseded. The history of a reversal is more valuable than the tidy log you would get by editing it out — it is the record of what was tried and what it cost.

Reading It Back

After a few months the log holds dozens of entries, and reading it top to bottom is the single best explanation of why the system looks the way it does. Annually, every record gets re-read and either reaffirmed or revised. And when a new person — or a new model — takes over maintaining the system, the decision log is the hand-over document nobody had to write.

Together with the Feedback Log

The decision log and the feedback log are the two files that make the system honest: one records what it might be wrong about now, the other records where it was wrong before. If you build only three files from this whole site, build the constitution and these two.

See it

The demo vault has twenty-seven records — and ADR-25, which reverses ADR-22 by the exact condition attached to it six days earlier. It is fictional, and it was built by Claude Code sessions running the bootstrap prompt — not written by hand.

#adr · #decisions · #learning