/design-review

name: design-review
description: "Reviews a game design document for completeness, internal consistency, implementability, and adherence to project design standards. Run this before handing a design document to programmers."
argument-hint: "[path-to-design-doc] [--depth full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion
model: sonnet

Phase 0: Parse Arguments

Extract `--depth [full|lean|solo]` if present. Default is `full` when no flag is given.

**Note**: `--depth` controls the *analysis depth* of this skill (how many specialist agents are spawned). It is independent of the global review mode in `production/review-mode.txt`, which controls director gate spawning. These are two different concepts — `--depth` is about how thoroughly *this* skill analyses the document.

• **`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

Read the target design document in full. Read CLAUDE.md to understand project context and standards. Read related design documents referenced or implied by the target doc (check `design/gdd/` for related systems).

**Dependency graph validation:** For every system listed in the Dependencies section, use Glob to check whether its GDD file exists in `design/gdd/`. Flag any that don't exist yet — these are broken references that downstream authors will hit.

**Lore/narrative alignment:** If `design/gdd/game-concept.md` or any file in `design/narrative/` exists, read it. Note any mechanical choices in this GDD that contradict established world rules, tone, or design pillars. Pass this context to `game-designer` in Phase 3b.

**Prior review check:** Check whether `design/gdd/reviews/[doc-name]-review-log.md` exists. If it does, read the most recent entry — note what verdict was given and what blocking items were listed. This session is a re-review; track whether prior items were addressed.

---

Phase 2: Completeness Check

Evaluate against the Design Document Standard checklist:

• [ ] Has Overview section (one-paragraph summary)
• [ ] Has Player Fantasy section (intended feeling)
• [ ] Has Detailed Rules section (unambiguous mechanics)
• [ ] Has Formulas section (all math defined with variables)
• [ ] Has Edge Cases section (unusual situations handled)
• [ ] Has Dependencies section (other systems listed)
• [ ] Has Tuning Knobs section (configurable values identified)
• [ ] Has Acceptance Criteria section (testable success conditions)

---

Phase 3: Consistency and Implementability

**Internal consistency:**

• Do the formulas produce values that match the described behavior?
• Do edge cases contradict the main rules?
• Are dependencies bidirectional (does the other system know about this one)?

**Implementability:**

• Are the rules precise enough for a programmer to implement without guessing?
• Are there any "hand-wave" sections where details are missing?
• Are performance implications considered?

**Cross-system consistency:**

• Does this conflict with any existing mechanic?
• Does this create unintended interactions with other systems?
• Is this consistent with the game's established tone and pillars?

---

Phase 3b: Adversarial Specialist Review (full mode only)

**Skip this phase in `lean` or `solo` mode.**

**This phase is MANDATORY in full mode.** Do not skip it.

**Before spawning any agents**, print this notice: > "Full review: spawning specialist agents in parallel. This typically takes 8–15 minutes. Use `--review lean` for faster single-session analysis."

Step 1 — Identify all domains the GDD touches

Read the GDD and identify every domain present. A GDD can touch multiple domains simultaneously — be thorough. Common signals:

| If the GDD contains... | Spawn these agents | |------------------------|-------------------| | Costs, prices, drops, rewards, economy | `economy-designer` | | Combat stats, damage, health, DPS | `game-designer`, `systems-designer` | | AI behaviour, pathfinding, targeting | `ai-programmer` | | Level layout, spawning, wave structure | `level-designer` | | Player progression, XP, unlocks | `economy-designer`, `game-designer` | | UI, HUD, menus, player-facing displays | `ux-designer`, `ui-programmer` | | Dialogue, quests, story, lore | `narrative-director` | | Animation, feel, timing, juice | `gameplay-programmer` | | Multiplayer, sync, replication | `network-programmer` | | Audio cues, music triggers | `audio-director` | | Performance, draw calls, memory | `performance-analyst` | | Engine-specific patterns or APIs | Primary engine specialist (from `.claude/docs/technical-preferences.md`) | | Acceptance criteria, test coverage | `qa-lead` | | Data schema, resource structure | `systems-designer` | | Any gameplay system | `game-designer` (always) |

Spawn `game-designer` for all GDDs that describe gameplay mechanics or player-facing rules. Spawn `systems-designer` for all GDDs that contain formulas or system interaction rules. These are the most common baselines — but not required for pure UI specs, audio specs, or lore documents. Use the domain table above to determine which specialists are truly relevant.

Step 2 — Spawn all relevant specialists in parallel

**CRITICAL: Task in this skill spawns a SUBAGENT — a separate independent Claude session with its own context window. It is NOT task tracking. Do NOT simulate specialist perspectives internally. Do NOT reason through domain views yourself. You MUST issue actual Task calls. A simulated review is not a specialist review.**

Issue all Task calls simultaneously. Do NOT spawn one at a time.

**Prompt each specialist adversarially:** > "Here is the GDD for [system] and the main review's structural findings so far. > Your job is NOT to validate this desi