← Patterns / prep
Decisions as their own artifacts
A spec says what we intend now. A decision doc says the moment that changed, and why.
- Authors
- Michael Staton
- Augmented with
- Claude Code on Claude Opus 5.5
- Tags
- Decisions
What it is
A short doc in
context-v/decisions/
: what was decided, when, by whom, and which alternatives were passed over. Kin to Architecture Decision Records, but not limited to architecture.
Why
Specs get rewritten as intent changes, which erases the record of why it changed. Six months later, someone proposes the rejected option again. A decision doc preserves the moment.
How
-
One decision per doc, short.
-
Name the alternatives and why they lost. That's the part people need later.
-
When the decisions are small, an append-only decisions log inside a long-running exploration works too.