We debated the same decision in three meetings
Cache layer or read replica? Each meeting reopened the same trade-offs. Nobody had the prior context in front of them.
Same debate, three meetings
The team was growing. Constraints shifted. Chat threads buried the reasoning.
Reasoning lived in chat
Decisions lived in memory. New joiners argued from scratch. We were paying meeting tax for missing paper.
Context beats conclusion
Write context, options rejected, and owner. Keep it short. Store it next to the code.
Review when reality changes. A stale note erodes trust.
Eight-line decision note
# Use read replica for reporting
Status: accepted
Context: dashboards hammer primary DB
Decision: replica for reads; 5m lag OK
Rejected: cache layer (invalidation risk)
Owner: platform team
Review: after Q3 traffic shapeWrite it once
Write it once. Point people to it. Good docs answer the same question one time.