JoelBonito/doc-review

Documentation Review Framework

"A document nobody trusts is worse than no document at all."

Purpose

Provide a structured methodology for reviewing planning documents generated by the /define workflow, ensuring consistency, completeness, traceability, and quality across all artifacts.

---

1. Review Process

Review Flow

Document Generated (Antigravity)
    │
    ├── Phase 1: Structural Review (completeness)
    ├── Phase 2: Cross-Document Consistency
    ├── Phase 3: GAP Analysis Validation
    ├── Phase 4: Quality & Precision Audit
    └── Phase 5: Traceability Verification
    │
    ▼
Review Report Generated
    │
    ├── APPROVED → Proceed to next phase
    ├── NEEDS REVISION → Specific issues listed
    └── REJECTED → Fundamental problems identified

Review Verdict Scale

| Verdict | Meaning | Action | |---------|---------|--------| | APPROVED | Document meets all quality criteria | Proceed | | APPROVED WITH NOTES | Minor issues, non-blocking | Proceed + log notes | | NEEDS REVISION | Specific sections need rework | Return to author with issues | | REJECTED | Fundamental quality problems | Full rework required |

---

2. Phase 1: Structural Review (Completeness)

Verify each document contains all required sections.

Brief Checklist

• [ ] Vision statement (one sentence + template format)
• [ ] Problem statement with evidence
• [ ] Solution description with UVP table
• [ ] 5 core MVP features with justification
• [ ] Primary + secondary personas
• [ ] Anti-persona defined
• [ ] North Star metric + tracking metrics
• [ ] Risks and mitigations table
• [ ] Approval section

PRD Checklist

• [ ] Functional requirements (P0/P1/P2 classified)
• [ ] Each RF has Gherkin acceptance criteria
• [ ] Edge cases documented per requirement
• [ ] Business rules with conditions and exceptions
• [ ] Non-functional requirements (performance, scalability, security, accessibility)
• [ ] User journeys with Mermaid flowcharts
• [ ] Integration specifications
• [ ] Traceability matrix
• [ ] Glossary of terms
• [ ] GAP Analysis: Product/Business section present

UX Concept Checklist

• [ ] Information Architecture (app map)
• [ ] Navigation pattern selection with rationale
• [ ] User flows for all primary journeys (Mermaid)
• [ ] Task flows with step tables
• [ ] Screen descriptions (textual wireframes)
• [ ] States per screen (empty, loading, error, success)
• [ ] Heuristic evaluation (Nielsen's 10)
• [ ] Friction mapping with severity scores
• [ ] Accessibility assessment (WCAG AA)
• [ ] Persona-flow matrix
• [ ] GAP Analysis: Experience section present

Architecture Checklist

• [ ] C4 Level 1 (System Context) diagram
• [ ] C4 Level 2 (Container) diagram
• [ ] Architecture pattern selection with rationale
• [ ] ADRs for significant decisions
• [ ] Database schema (ERD + table specs)
• [ ] Integration mapping
• [ ] Security architecture (auth, authorization)
• [ ] Environment strategy
• [ ] Scaling strategy
• [ ] Observability plan
• [ ] GAP Analysis: Infrastructure section present

Stack Checklist

• [ ] Technology selection per layer with rationale
• [ ] Alternatives considered per choice
• [ ] Version specifications
• [ ] Compatibility matrix
• [ ] Deprecation awareness
• [ ] Required libraries/tools list
• [ ] Development tooling
• [ ] GAP Analysis: Technology section present

Design System Checklist

• [ ] Design principles (3-5 principles)
• [ ] Color palette with tokens (primary, secondary, semantic, neutral)
• [ ] Dark mode mapping (if applicable)
• [ ] Typography system (families, scale, weights)
• [ ] Spacing system (base unit + scale)
• [ ] Layout system (breakpoints, container, grid)
• [ ] Component specifications (buttons, inputs, cards, modals)
• [ ] Component states (default, hover, focus, error, disabled, loading)
• [ ] Iconography library selection
• [ ] Animation/transition specifications
• [ ] Accessibility checklist per component
• [ ] GAP Analysis: Design section present

Backlog Checklist

• [ ] Epic breakdown (3-7 epics)
• [ ] Stories per epic with acceptance criteria
• [ ] Subtasks with technical specifics
• [ ] Dependency graph (Mermaid)
• [ ] Execution order
• [ ] Progress tracking table
• [ ] Consolidated GAP Summary section present
• [ ] GAP-to-Task Mapping table present
• [ ] Roadmap to Close Gaps section present

---

3. Phase 2: Cross-Document Consistency

Terminology Consistency

### Terminology Audit

| Term | Brief | PRD | UX | Architecture | Stack | Design | Backlog | Consistent? |
|------|-------|-----|----|-------------|-------|--------|---------|-------------|
| [Term 1] | [Usage] | [Usage] | [Usage] | [Usage] | [Usage] | [Usage] | [Usage] | Yes/No |

Rules:

• Same entities must use same names across all documents
• Persona names must be identical everywhere
• Feature names must match between Brief, PRD, and Backlog
• Technical terms must be consistent (e.g., don't mix "endpoint" and "route")

Requirement Traceability

### Traceability Matrix

| Feature (Brief) | Requirement (PRD) | Flow (UX) | Component (Architecture) | Epic/Story (Backlog) | Covered? |
|------------------|--------------------|-----------|--------------------------|----------------------|----------|
| [Feature 1] | RF01 | Flow 1 | API Controller A | Epic 1 / Story 1.1 | Yes/No |
| [Feature 2] | RF02 | Flow 2 | API Controller B | Epic 1 / Story 1.2 | Yes/No |

Every feature in the Brief MUST trace through all documents to a Backlog story.

Priority Alignment

| Requirement | PRD Priority | Backlog Priority | Aligned? | Issue | |-------------|-------------|-----------------|----------|-------| | RF01 | P0 | Epic 1 (first) | Yes/No | [If no, explain] |

Number Consistency

Check that quantities, limits, and metrics are consistent:

| Metric | Brief Value | PRD Value | Architecture Value | Aligned? | |--------|------------|-----------|-------------------|----------| | Max users | [Value] | [Value] | [Value] | Yes/No | | Response time | [Value] | [Value] | [Value] | Yes/No | | Storage limit | [Value] | [Value] | [Value] | Yes/No |

---

4. Phase 3: GAP Analysis Validation

GAP Completeness Check

| Document | GAP Section Present? | GAPs Identified | All Have IDs? | All Have Severity? | All Mapped to Backlog? | |----------|---------------------|-----------------|---------------|--------------------|-----------------------| | PRD | Yes/No | [N] | Yes/No | Yes/No | Yes/No | | UX Concept | Yes/No | [N] | Yes/No | Yes/No | Yes/No | | Architecture | Yes/No | [N] | Yes/No | Yes/No | Yes/No | | Stack | Yes/No | [N] | Yes/No | Yes/No | Yes/No | | Design System | Yes/No | [N] | Yes/No | Yes/No | Yes/No |

GAP ID Format Validation

All GAP IDs must follow the pattern G-{DIM}-{NN}:

• G-PRD-01 for Product gaps
• G-UX-01 for Experience gaps
• G-ARCH-01 for Architecture gaps
• G-STACK-01 for Technology gaps
• G-DS-01 for Design gaps

Orphan GAP Check

Every GAP must appear in the Backlog's consolidated summary:

### Orphan GAP Report

| GAP ID | Source Document | In Backlog? | Issue |
|--------|----------------|-------------|-------|
| [ID] | [Document] | Yes/No | [If no, needs mapping] |

---

5. Phase 4: Quality & Precision Audit

Vagueness Detection

Scan for imprecise language and flag:

| Document | Section | Vague Term Found | Suggested Replacement | |----------|---------|------------------|----------------------| | [Doc] | [Section] | "several users" | "100 concurrent users" | | [Doc] | [Section] | "fast response" | "< 200ms (p95)" | | [Doc] | [Section] | "handle many requests" | "1,000 req/min" |

Common Vague Terms to Flag

| Vague | Should Be | |-------|-----------| | "fast", "quick", "responsive" | Specific ms/s threshold | | "many", "several", "various" | Exact number or range | | "some", "a few" | Exact count | | "etc.", "and more", "and so on" | Complete list | | "should be good", "adequate" | Measurable criteria | | "simple", "easy to use" | Specific UX criteria | | "scalable" | Specific capacity numbers | | "secure" | Specific security measures |

Measurability Check

For each metric, requirement, or criterion:

• [ ] Has a specific numeric target?
• [ ] Has a measurement method?
• [ ] Has a success threshold?
• [ ] Is it testable/verifiable?

Actionability Check

For each item in the Backlog:

• [ ] Has clear INPUT (what's needed to start)?
• [ ] Has clear OUTPUT (what's produced)?
• [ ] Has clear VERIFY (how to confirm it's done)?
• [ ] Can be assigned to a specific agent?

---

6. Phase 5: Traceability Verification

Full Traceability Chain

Brief Feature → PRD Requirement → UX Flow → Architecture Component → Stack Technology → Design Component → Backlog Story

Every item must chain through. Breaks in the chain indicate:

• Missing documentation
• Orphan features (defined but not planned)
• Orphan tasks (planned but not justified)

Coverage Report

### Traceability Coverage

| Dimension | Items Defined | Items Traced | Coverage % | Orphans |
|-----------|--------------|-------------|-----------|---------|
| Features (Brief) | [N] | [N] | [%] | [List] |
| Requirements (PRD) | [N] | [N] | [%] | [List] |
| Flows (UX) | [N] | [N] | [%] | [List] |
| Components (Arch) | [N] | [N] | [%] | [List] |
| Stories (Backlog) | [N] | [N] | [%] | [List] |

---

7. Review Report Template

# Documentation Review Report

## Metadata
- **Reviewer:** [Claude Code / Codex]
- **Date:** {YYYY-MM-DD}
- **Documents Reviewed:** [List]
- **Overall Verdict:** APPROVED / APPROVED WITH NOTES / NEEDS REVISION / REJECTED

---

## Summary

| Document | Structural | Consistency | GAP Quality | Precision | Traceability | Verdict |
|----------|-----------|------------|-------------|-----------|-------------|---------|
| Brief | Pass/Fail | Pass/Fail | N/A | Pass/Fail | Pass/Fail | [Verdict] |
| PRD | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |
| UX Concept | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |
| Architecture | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |
| Stack | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |
| Design System | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |
| Backlog | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail | [Verdict] |

---

## Issues Found

### Critical (Must Fix)
1. [Issue description + document + section]

### Major (Should Fix)
1. [Issue description + document + section]

### Minor (Nice to Fix)
1. [Issue description + document + section]

---

## Recommendations
1. [Actionable recommendation]

---

Rules

1. Review ALL documents before issuing verdict — Cross-document issues are invisible in isolation
2. Be specific — "Section 3.2 uses 'fast' without a metric" not "document is vague"
3. Severity matters — Don't block on minor issues, don't approve with critical ones
4. Traceability is binary — Either an item is traced end-to-end or it's not
5. Vague terms are bugs — Flag every instance, suggest specific replacement
6. GAP orphans are failures — Every GAP must map to a Backlog task
7. Consistency is non-negotiable — Same term, same meaning, everywhere