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:

1. •Summarize current state
2. •Cross-check against new learnings
3. •Ask clarifying questions
4. •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

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