ADR
03-knowledge/decisionsAn architectural decision. In force until superseded; read before changing the area.
What it is
An Architectural Decision Record captures a significant choice and the reasoning behind it — 'we chose X over Y because…'. It stays in force until explicitly superseded, so future sessions don't quietly undo decisions they don't understand.
When to write it
When you make a call with lasting consequences — a stack choice, a structural trade-off, a security decision.
What goes in it
- The decision, stated plainly
- The context and the options considered
- The consequences and trade-offs accepted
- Status: accepted / superseded / deprecated
How it fits
The third knowledge artefact type. Any session considering a change to the area should read its ADR first.
Get the templatestarter/docs/03-knowledge/decisions/knowledge-adr.md