design-review skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,system_overrides

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

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; automationalwaysask categories always prompt).

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

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.

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

sections advisorily.

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

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 (~46k tokens, measured) 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"

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 listed line reads UNCHANGED (an absent registry simply doesn't appear in the output and doesn't block the skip).

"This document is byte-identical to its last review on [date] (verdict: [verdict])." If that verdict was APPROVED, 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 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.

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

verdict stands except for cross-document facts: re-verify the doc's registry-sourced values against the new registry and re-issue the verdict; escalate to a full re-review only if a conflict appears.

• Only the registry line reads CHANGED (doc UNCHANGED) — the prior

full review below. Do not offer a partial/delta re-review that skips reading or re-analyzing unchanged sections. Measured against a full review: three independent designs (a straightforward section-scoped pass, one with an explicit forced whole-document scan step, and one gated on a genuinely thorough two-round prior review) each caught only 2 of 6 real defects a full review found on the same document, and the most careful version cost more tokens than the full review while catching the same reduced fraction. "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 no amount of "scan everything anyway" instruction reliably overcame a model's attention naturally narrowing to the flagged change.

• Target doc CHANGED or NEW, or RECEIPT: NONE — proceed with the

Read the target design document in full. Read CLAUDE.md to understand project context and standards.

For cross-document facts, prefer the registry over sibling GDDs. If design/registry/entities.yaml exists and lists entries for this system, grep it — these are the established facts this GDD must not contradict, and they replace reading sibling GDDs to rediscover them:

Grep pattern="source: design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -A 6
Grep pattern="design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -B 8

The first finds entries this system owns — the -A 6 context includes their referencedby: block. The second finds entries that reference this system — referencedby: is a block sequence (the key and its paths are on separate lines), so match the path with -B 8 context to see the owning entry, not a referencedby.name one-liner (which never matches the block form).

If design/registry/entities.yaml does not exist, or lists no entry for this system — the file ships as an empty stub, so this is the default until /design-system has populated it — fall back to reading the related GDDs the target doc names in its Dependencies section. Bound the read to those, not to everything "implied". Do not glob-read all of design/gdd/.

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

Step 2a — gather section presence deterministically (no document read):

Bash: bash .claude/scripts/gdd-structure-check.sh [target-doc-path]

It prints a PRESENT: list and, when applicable, an ABSENT: list. It reports presence only and makes no REQUIRED/ADVISORY judgment — that is Step 2b's job. It already accepts ## Detailed Design as satisfying the Detailed Rules requirement, so do not flag that as missing.

Step 2b — apply the tier. Using the Step 2a lists, evaluate against the Design Document Standard checklist below. Mark each section REQUIRED or ADVISORY per the resolved workflow tier (Phase 0). A missing REQUIRED section blocks approval; a missing ADVISORY section is surfaced as a recommendation but does not block.

A section reported PRESENT can still fail review if it is an empty heading — spot-read any section the verdict actually turns on.

• [ ] Has Overview section (one-paragraph summary) — REQUIRED at all tiers
• [ ] Has Player Fantasy section (intended feeling) — REQUIRED at full; ADVISORY at standard
• [ ] Has Detailed Rules section (unambiguous mechanics) — REQUIRED at full/standard. The GDD template titles this section ## Detailed Design (it carries Core Rules / States / Interactions sub-headings); accept either heading as satisfying this requirement — do not flag "Detailed Rules" as missing when a ## Detailed Design section is present.
• [ ] Has Formulas section (all math defined with variables) — REQUIRED at full; at standard REQUIRED whenever the system defines numeric rules (rates, curves, thresholds, costs, damage, drop weights), else ADVISORY. The system's Category is a hint, not the test — do not clear this on a category token alone
• [ ] Has Edge Cases section (unusual situations handled) — REQUIRED at full/standard
• [ ] Has Dependencies section (other systems listed) — REQUIRED at full/standard
• [ ] Has Tuning Knobs section (configurable values identified) — REQUIRED at full; ADVISORY at standard unless workflowoverrides.tuningknobs
• [ ] Has Acceptance Criteria section (testable success conditions) — REQUIRED at full/standard

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

Using the GDD already loaded in Phase 1 — do not re-read it — identify every domain present. A GDD can touch multiple domains simultaneously — be thorough. Common signals:

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: Agent 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 Agent calls. A simulated review is not a specialist review.

Issue all Agent 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 design — your job is to find problems.

Challenge the design choices from your domain expertise. What is wrong,

underspecified, likely to cause problems, or missing entirely?