04. Decision Records and ADRs — The ship's log remembers¶
~13 min read. Good teams do not trust memory alone. They keep a ship's log.
Built on the ELI5 in 00-eli5.md. the ship's log —
reminder of documentation and ADRs — keeps one-way decisions alive after people move on.
1) Why the ship's log matters¶
See. A captain does not rely on mood when steering.
Important choices get written down. Why?
Because the sea changes. The crew changes.
Assumptions change. Without a ship's log,
teams remember outcomes but forget reasons. That is dangerous.
An ADR fixes that. It is not a giant design novel.
It is a compact decision record. It says what was decided,
why it was decided, what alternatives were considered,
and what consequences follow.
┌──────────────────────────────┐
│ Decision appears │
├──────────────────────────────┤
│ Context is written │
├──────────────────────────────┤
│ Options are compared │
├──────────────────────────────┤
│ Choice is recorded │
├──────────────────────────────┤
│ Revisit trigger is defined │
└──────────────────────────────┘
It protects future judgement. It also protects the crew from repeated circular debate.
Simple, no?
2) The ADR template that actually helps¶
So what to do? Use a small template consistently.
That matters more than perfect prose. A useful ADR usually has these fields.
- Title
- Status
- Context
- Options considered
- Decision
- Consequences
- Revisit triggers See why each part matters. Title keeps the record searchable.
Status shows whether it is proposed, accepted, or superseded. Context explains the pressure around the choice.
Options considered stop false memory later. Decision states the call clearly.
Consequences force honesty about trade-offs. Revisit triggers stop principles from becoming dogma.
Yes? That last one matters a lot.
Without revisit triggers, an old shortcut becomes permanent scripture.
The compass becomes rigid. The course stops adapting.
The weather check gets ignored because somebody says, 'We already decided this once.'
That is not discipline. That is stale thinking.
3) Strong ADRs explain why alternatives lost¶
Many weak ADRs record only the winner. That is half useful.
Strong ADRs also explain why the loser lost. See the difference.
Weak version: 'We chose provider A for embeddings.'
That tells the future almost nothing. Strong version:
'We chose provider A because launch urgency is high, data sensitivity is moderate, and current volume does not justify self-hosting burden. Provider B lost because it required slower integration. Self-hosting lost because cost and control benefits are still unproven.' Now the crew can reason properly later.
If urgency drops, or if volume rises,
the decision can be revisited intelligently. The ship's log now carries judgement,
not just memory. Simple, no?
Also notice this. Good ADRs mention trade-offs openly.
Latency may improve while cost worsens. Control may improve while operator burden worsens.
Quality may improve while reversibility worsens. That honesty is the whole point.
An ADR is not a victory speech. It is a navigation record.
4) Revisit triggers keep principles alive, not frozen¶
Look. A principle without a revisit trigger can become stubbornness.
That is why this field deserves real attention. Good revisit triggers sound like this.
- Revisit if monthly query volume crosses the current cost threshold.
- Revisit if eval quality drops below the agreed bar for two releases.
- Revisit if security policy changes the allowed data boundary.
- Revisit if on-call burden exceeds the current team capacity.
- Revisit if vendor latency stays above the user promise for one quarter. See how practical that feels. These triggers tie the decision back to evidence.
They reconnect the compass to reality. They force a fresh weather check when conditions change.
And they stop the ship's log from becoming a graveyard of old certainty. Yes?
One more rule. Keep ADRs easy to find.
If the crew cannot discover them quickly, they do not exist operationally.
Link them from the repo. Reference them in planning.
Update status when superseded. That is how documentation stays alive.
Where this lives in the wild¶
- Enterprise AI platform — staff engineer records why the team stayed API-first instead of self-hosting.
- Product search assistant — architect documents why retrieval was added before fine-tuning for domain freshness.
- Voice agent team — engineering manager logs why a provider contract was accepted despite reduced reversibility.
- Clinical summarisation product — ML lead records consequences and revisit triggers for handling sensitive data paths.
- Developer productivity copilot — platform lead documents why one eval stack was chosen over a faster but noisier alternative.
Pause and recall¶
- Why is recording only the final choice not enough?
- Which ADR field prevents old decisions from turning into dogma?
- How does the ship's log help new crew members specifically?
- Name the seven template fields from this file.
Interview Q&A¶
Q: What makes an ADR valuable instead of ceremonial?
A: It captures decision context, rejected alternatives, consequences, and revisit triggers in a compact form people can actually reuse.
Common wrong answer to avoid: An ADR is valuable mainly because architecture teams expect formal documents.
Q: Why must strong ADRs explain why alternatives lost?
A: Future teams need the judgement behind the choice, not only the output. That context makes reconsideration intelligent when conditions shift.
Common wrong answer to avoid: Listing rejected options is enough, even without reasons.
Q: Why are revisit triggers essential?
A: They tie the decision to changing evidence and stop temporary trade-offs from turning into untouchable doctrine.
Common wrong answer to avoid: Revisit triggers matter only for experimental systems.
Q: When should teams write an ADR?
A: Write one when the decision is sticky, cross-functional, expensive, risky, or likely to be debated again later.
Common wrong answer to avoid: ADRs should be written for every tiny implementation detail.
Apply now (5 min)¶
Exercise: Take one recent one-way door decision.
Write a seven-part ADR for it in bullets. Then add one sentence for why the strongest rejected option lost.
Sketch from memory: Draw the five-step ADR flow from this file.
Under the last box, write three concrete revisit triggers.
Bridge. ADRs record what the team promised. Next we need instruments that show whether the system is actually keeping those promises.