Design-First Review Workflow
Review the intended design before implementation so structural problems are caught before code is written.
Objective
Catch design problems before they are baked into implementation.
Environment
- A design document or diagram
- Reviewers with domain context
- A discussion channel
Steps
1. Present the design and trade-offs
Describe the approach, alternatives considered, and why this one was chosen.
Expected state: Reviewers understand the decision and its alternatives.
2. Review against requirements
Check the design actually satisfies the functional and non-functional needs.
Expected state: The design covers the real requirements.
3. Review failure and edge behaviour
Examine how the design behaves under failure, load, and edge conditions.
Expected state: Failure modes are designed for, not discovered later.
4. Decide and record
Approve, request changes, or reject with recorded rationale.
Expected state: The design decision is documented before implementation.
Decision points
Review the design or start coding?
- Review significant designs first
- Start coding immediately
Review significant or irreversible designs before writing code.
Who reviews?
- Domain owners plus a generalist
- Anyone available
Combine domain expertise with a generalist for blind spots.
Expected outcome
Structural problems are caught at design time when they are cheapest to change.
Verification
Confirm the design covers requirements and failure modes and the decision is recorded.
Cleanup
Archive the design decision and link it from the implementation.
Overview
Catch design problems before they are baked into implementation.
This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.
Environment and prerequisites
- A design document or diagram
- Reviewers with domain context
- A discussion channel
Procedure
1. Present the design and trade-offs
Describe the approach, alternatives considered, and why this one was chosen.
Expected state: Reviewers understand the decision and its alternatives.
2. Review against requirements
Check the design actually satisfies the functional and non-functional needs.
Expected state: The design covers the real requirements.
3. Review failure and edge behaviour
Examine how the design behaves under failure, load, and edge conditions.
Expected state: Failure modes are designed for, not discovered later.
4. Decide and record
Approve, request changes, or reject with recorded rationale.
Expected state: The design decision is documented before implementation.
# record the design decision
adr new 'Use event sourcing for order history'Verification
Confirm the design covers requirements and failure modes and the decision is recorded.
Decision points
Review the design or start coding?
- Review significant designs first
- Start coding immediately
Recommendation: Review significant or irreversible designs before writing code.
Who reviews?
- Domain owners plus a generalist
- Anyone available
Recommendation: Combine domain expertise with a generalist for blind spots.
Common failures
- Design flaws found after implementation cost far more.
- Unexamined failure modes surface in production.
- Unrecorded decisions get re-litigated.