/design-review

name: design-review
description: "Reviews one design document for completeness, internal consistency, implementability, and design standards. Before handing to programmers."
argument-hint: "[path-to-design-doc] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/design-review/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/review-receipts.sh check *), Bash(bash .claude/scripts/review-receipts.sh hash *), Bash(bash .claude/scripts/gdd-structure-check.sh *), Bash(grep -E '^  - name:' design/registry/entities.yaml), Bash(grep -n -i -E *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides`

Resolved above — use as-is; `--review` overrides `review_mode`. `--depth` is the pre-1.1 name for the same flag: treat `--depth <mode>` exactly as `--review <mode>`, and say once that it was renamed. Given both, `--review` wins and `--depth` is ignored — say so. No block → defaults in `.claude/docs/config-resolution.md`.

Design Review

Phase 0: Parse Arguments

See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session.

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

**`workflow`** for the GDD under review — use the `system_overrides` row for `<system>` if the block lists one, else the project value. Validation scope follows the tier:

• `full` — all 8 sections validated; any missing section blocks approval.
• `standard` — the 5 required sections (Overview, Detailed Rules, Edge Cases,

Dependencies, Acceptance Criteria) block if missing; Formulas blocks only when the system defines numeric rules (rates, curves, thresholds, costs — the category is a hint, not the test); Player Fantasy and Tuning Knobs are advisory (warn, never block) unless `workflow_overrides` require them.

• `minimal` — no GDD is expected; if one exists, validate the 5 standard

sections advisorily.

Resolved mode controls how thorough this review is:

• **`full`**: Complete review — all phases + specialist agent delegation (Phase 3b)
• **`lean`**: All phases, no specialist agents — faster, single-session analysis
• **`solo`**: Phases 1-4 only, no delegation, no Phase 5 next-step prompt — use when called from within another skill

---

Phase 1: Load Documents

**Freshness check first — a re-review of an unchanged document costs full price and reproduces the same verdict.** Run:

Bash: bash .claude/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".claude/skills/design-review/SKILL.md"

The registry is in the check because this review consults it for cross-document facts — an unchanged GDD reviewed against a *changed* registry can reach different conclusions, so the skip is only safe when **every** line reads `UNCHANGED` (a registry that never existed doesn't appear in the output and doesn't block the skip). This skill's file is in it because a changed skill reviews differently. The check also compares every other file the log stamps — the related GDDs, concept or brief and narrative files earlier reviews read — and prints `GONE:` for one that no longer exists.

Then read the latest entry's `Review mode:` line. That review **covers** this run only when its mode is the same as or deeper than the mode resolved now (`full` > `lean` > `solo`) and its workflow is the same or deeper (`full` > `standard` > `minimal`). An entry without the line was written before it existed and covers nothing.

• **All `UNCHANGED`** and the log's latest entry carries a verdict — surface it:

*"This document is byte-identical to its last review on [date] ([mode] review, verdict: [verdict])."* If that verdict was APPROVED and that review covers this run, offer via `AskUserQuestion`: `[A] Use the prior verdict (Recommended)` / `[B] Re-review anyway` — `guided` proceeds with [A] and notes it; `autonomous` logs via `log_decision` and uses the prior verdict. If it was APPROVED but the review asked for now is deeper than the logged one, say so — *"That was a [mode] review at workflow [tier]; this run asks for [mode] at [tier]."* — and offer `[A] Re-review at [mode] (Recommended)` / `[B] Use the prior [mode] verdict`; `guided` and `autonomous` re-review (`autonomous` logs it via `log_decision`). If it was NEEDS REVISION or MAJOR REVISION NEEDED, say so plainly: the document has not changed since it failed review — the prior findings stand; revising the document is the next step, not re-reviewing it. Offer to display the prior findings from the log.

• **The target doc and this skill's file `UNCHANGED`, and only the registry or

another stamped cross-document file `CHANGED`, `NEW` or `GONE`** — the prior verdict stands except for cross-document facts: re-verify the doc's values against the changed files and re-issue the verdict; escalate to a full re-review if a conflict appears or that review does not cover this run.

• **Target doc or this skill's file `CHANGED` or `NEW`, or `RECEIPT: NONE`** —

proceed with the full review below. **Do not offer a partial/delta re-review that skips reading or re-analyzing unchanged sections.** A section-scoped re-review misses defects a full review finds, and saves little or nothing. "Unchanged since last review" only means byte-identical to what was reviewed then — it says nothing about whether that prior pass was itself complete, and attention narrows to the flagged change even under an instruction to scan everything anyway.

Read the target design