Last updated: YYYY-MM-DD
Chosen: (what you went with) Why: (the reasoning — usually one or two sentences) Considered and ruled out: (alternatives, why they didn't fit) Cost / tradeoff: (what this decision is bad at)
- When you make a non-obvious choice, log it here. Even small ones — "use library X over Y because of Z."
- When you reverse a decision, add a new entry on top and add
**Superseded by:** [link or date]to the old one. Don't delete the old reasoning. - When you read code that confuses you, check here. If the rationale isn't logged, that's a gap worth filling.