reviewing-design-docs

Invariant Principles

1. Specification sufficiency determines implementation success. Underspecified designs force implementers to guess, causing divergent implementations and rework.
2. Method names are suggestions, not contracts. Inferred behavior from naming is fabrication until verified against source.
3. Vague language masks missing decisions. "Standard approach", "as needed", "TBD" defer design work to implementation phase where it costs 10x more.
4. Complete != comprehensive. Document completeness means every item either specified or explicitly N/A with justification.

Inputs

Outputs

Reasoning Schema

<analysis>
[Document section under review]
[Specific claim or specification]
[What implementation decision this enables or blocks]
</analysis>

<reflection>
[Could I code against this RIGHT NOW?]
[What would I have to invent/guess?]
[Verdict: SPECIFIED | VAGUE | MISSING]
</reflection>

Example verdict: "Authentication timeout: 30s" → SPECIFIED. "Retry on failure: standard approach" → VAGUE (retry count, backoff unspecified). "Rate limiting" → MISSING (no mention).

Phase 1: Document Inventory

## Sections: [name] - lines X-Y
## Components: [name] - location
## Dependencies: [name] - version: Y/N
## Diagrams: [type] - line X

Phases 2-3: Completeness Checklist + Hand-Waving Detection

Evaluate every category for specification completeness. Detect vague language, assumed knowledge, and magic numbers.

Execute: /review-design-checklist

Outputs: Completeness matrix with SPECIFIED/VAGUE/MISSING verdicts, vague language inventory, assumed knowledge list, magic number list

Optional deep audit: For specs with 3+ VAGUE items, run /sharpen-audit on specific sections to get executor-prediction analysis (what an implementer would guess for each ambiguity).

Optional claim decomposition: For specification sections with dense factual content (3+ compound claims in a paragraph), invoke /decompose-claims to break them into atomic verifiable units before completeness scoring.

Phases 4-5: Interface Verification + Implementation Simulation

Verify all interface claims against source code. Escalate unverifiable claims to factchecker. Simulate implementation per component to surface gaps.

Execute: /review-design-verify

Outputs: Verification table, factchecker escalations, per-component implementation simulation

Phases 6-7: Findings Report + Remediation Plan

Compile scored findings report and prioritized remediation plan.

Execute: /review-design-report

Outputs: Score table, numbered findings with location and remediation, P1/P2/P3 remediation plan with factcheck and additions sections

Self-Check

[ ] Full document inventory
[ ] Every checklist item marked
[ ] All vague language flagged
[ ] Interfaces verified (source read, not assumed)
[ ] Claims escalated to factchecker
[ ] Implementation simulated per component
[ ] Every finding has location + remediation
[ ] Prioritized remediation complete

<FINAL_EMPHASIS> NOT "does this sound reasonable?"

"Could someone create a COMPLETE implementation plan WITHOUT guessing design decisions?"

For EVERY specification: "Is this precise enough to code against?"

If uncertain: under-specified. Find it. Flag it. </FINAL_EMPHASIS>