Decision Recording Expectations
What must be recorded
Record decisions that materially affect:
- product behavior
- business rules
- API and schema direction
- technical architecture
- AWS environment structure
- security and permission model
- standard tooling, frameworks, or approved libraries
- build/release/operations model
What does not need to be recorded
Do not record:
- every chat discussion
- every brainstorming branch
- transient back-and-forth that did not result in a decision
- routine implementation detail that does not change shared understanding
What a decision record should include
At minimum:
- title
- date
- status
- context
- decision
- consequences / follow-up
Where to record decisions
- Major shared decisions should live in shared governance/standards pages or in a dedicated app page when app-specific.
- If a decision exposes unresolved work, add a corresponding item to the gaps/drift register.
Quality bar
A decision record should help a new engineer answer:
- what was decided?
- why was it decided?
- where does it apply?
- what constraints does it create?