Proposal: decision as a related resource type #16
Description
Conversations are ephemeral.
The URL in a trace record might resolve to nothing six months from now: vendor APIs change, transcripts get deleted, sessions expire.
Decision records persist.
They live in the repo, version-controlled, and capture why a choice was made rather than the back-and-forth of how it was reached.
The related field already supports arbitrary types.
This would just document "decision" as a recognized one:
"related": [
{ "type": "decision", "url": "file:///docs/adr/0007-api-versioning.md" }
]No schema changes needed.
Producers that don't track decisions just don't include it.
Consumers that don't understand it skip it.
Why this matters in practice
Building with AI agents across multiple sessions, I kept hitting the same problem: the agent re-solves architectural decisions every session because it has no persistent memory of why previous choices were made.
Column naming conventions, normalization strategy, constraint handling: all rediscovered from scratch each time.
Linking trace records to decision records closes that loop.
Agent Trace tells you which conversation produced lines 42-67.
The decision record tells you why that approach was chosen over alternatives, and it survives even when the conversation doesn't.
Complements #9
With timestamps and correlation IDs (#9) plus decision links, you get the full chain: when → what → who → why.
Prior art
- Architecture Decision Records (Nygard)
- MADR
- Memory Trail - decision persistence for AI-assisted dev sessions