design-review

Design Review

Dispatch a reviewer subagent to validate a design doc before planning. Catches spec gaps that are cheap to fix in design but expensive to fix mid-implementation.

Core principle: Designs are hypotheses about what to build. Validate before committing to a plan.

When to Use

• After the design skill writes a design doc (auto-dispatched)
• When asked to review any existing design doc
• Before draft-plan is dispatched (hard gate)

Skip for: Trivially small changes with no design doc.

Dispatch

Gather inputs:

• Design doc — absolute path under $MAIN_ROOT/.claude/claude-caliper/YYYY-MM-DD-topic/design-topic.md (main repo, not worktree)
• Repo root — the worktree the design targets

Dispatch with model: "$DESIGN_REVIEWER_MODEL" — review requires strong reasoning to catch blind spots the designer and user converged past.

Use subagent_type: "claude-caliper:design-reviewer". See: reviewer-prompt.md for invocation template.

8-Point Checklist

1. Problem Clarity — specific problem, who is affected, consequences of not solving
2. Success Criteria Quality — human-verifiable, implementation-independent, collectively complete, individually necessary
3. Architecture-Problem Fit — architecture addresses stated problem, feasibility risks identified
4. Alternative Assessment — considers more effective or efficient approaches
5. Scope Alignment — solves stated problem and not more, non-goals correctly scoped
6. Decision Justification — key decisions include trade-off analysis
7. Internal Consistency — names, paths, concepts consistent across sections
8. Handoff Quality — plan drafter with zero context can produce correct plan from doc alone

Output

Reviewer produces:

• Issues Found (category, problem, fix with specific text suggestions)
• Assessment table (PASS/FAIL per check)
• "Ready for planning?" verdict

Pass: Zero issues, or all issues fixed and confirmed clean Fail: Return to design skill to fix, then re-run design-review

Re-review gate (design-review): The design skill controls the review loop with these rules:

• Batch-fix discipline: All issues from a review are triaged (fix or dismiss with reasoning) in one pass before re-dispatching
• Delta context (iter ≥2): Follow-up reviewers receive the prior iteration's issues with resolution status, enabling verify-then-scan instead of full re-discovery
• Severity-gated termination (after iter 3): Remaining low and medium issues are auto-dismissed; only high and critical issues block planning past iteration 3

Note: Plan-review uses a separate gate — caliper-settings get re_review_threshold. That gate is unchanged.

Integration

Auto-dispatched by: design (after design doc written)

Leads to: draft-plan (once review passes)