| name | design-review |
| description | Use when refining an architecture or design document based on new learnings, before a rewrite. Use when you have an existing doc and related docs to cross-check against. Use when you need systematic section-by-section validation of decisions. |
Design Review
Overview
Design review separates validation from rewriting. Go section-by-section through a design doc, cross-check against new learnings, record changes with rationale, then rewrite in a fresh session.
Core principle: Changes document first, rewrite second. Never edit inline.
When to Use
- Refining v1 → v2 of an architecture doc
- Incorporating implementation learnings into design
- Cross-checking design against related docs
- Validating past decisions after new context
Don't use: Writing from scratch (use brainstorming), minor edits, obvious changes.
Process
1. Create Changes Document
# [Design Name] v[N+1]: Changes
> After full review, create fresh v[N+1] incorporating all changes.
## Changes
2. Section-by-Section Review
For each section:
- Summarize current state
- Cross-check against new learnings
- Ask clarifying questions
- Record change or confirm unchanged
Questions to ask:
- Does this still hold given what we now know?
- Anything missing? Contradicts other sections?
- Right level of detail for this doc?
3. Change Format
### [N]. [Short Description]
**Section:** [Section name]
**Change:** [What's changing]
**Rationale:** [Why]
---
4. Structural Principles
| Principle | Meaning |
|---|
| Main body vs Appendix | "What we're doing" vs "paths we rejected" |
| No mixed content | Remove sections with undiscussed details mixed in |
| Feature sections own data | Each feature owns its endpoints/models, no central lists |
| No timelines | Architecture = what, not when |
5. Fresh Session Rewrite
Do NOT rewrite in same session. Start fresh with:
- Original design doc
- Changes document
- Related docs (reference)
Red Flags
- "I'll just fix this inline" → Use changes document
- "This section looks fine" → Confirm aloud or mark unchanged
- "I'll remember why" → Write rationale now
- "Let me rewrite now" → Fresh session required
- "Auto-generated but reasonable" → Validate or remove
Common Mistakes
| Mistake | Fix |
|---|
| Inline editing | Always use changes document |
| Skipping sections | Review every section |
| No rationale | Always include "why" |
| Same-session rewrite | Fresh session for rewrite |
| Keeping auto-generated details | Validate each or remove |
