/review-all-gdds

name: review-all-gdds
description: "Holistic cross-GDD consistency and game design review. Reads all system GDDs simultaneously and checks for contradictions between them, stale references, ownership conflicts, formula incompatibilities, and game design theory violations (dominant strategies, economic imbalance, cognitive overload, pillar drift). Run after all MVP GDDs are written, before architecture begins."
argument-hint: "[focus: full | consistency | design-theory | since-last-review]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Task
model: opus

Review All GDDs

This skill reads every system GDD simultaneously and performs two complementary reviews that cannot be done per-GDD in isolation:

1. **Cross-GDD Consistency** — contradictions, stale references, and ownership conflicts between documents 2. **Game Design Holism** — issues that only emerge when you see all systems together: dominant strategies, broken economies, cognitive overload, pillar drift, competing progression loops

**This is distinct from `/design-review`**, which reviews one GDD for internal completeness. This skill reviews the *relationships* between all GDDs.

**When to run:**

• After all MVP-tier GDDs are individually approved
• After any GDD is significantly revised mid-production
• Before `/create-architecture` begins (architecture built on inconsistent GDDs

inherits those inconsistencies)

**Argument modes:**

**Focus:** `$ARGUMENTS[0]` (blank = `full`)

• **No argument / `full`**: Both consistency and design theory passes
• **`consistency`**: Cross-GDD consistency checks only (faster)
• **`design-theory`**: Game design holism checks only
• **`since-last-review`**: Only GDDs modified since the last review report (git-based)

---

Phase 1: Load Everything

Phase 1a — L0: Summary Scan (fast, low tokens)

Before reading any full document, use Grep to extract `## Summary` sections from all GDD files:

Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5

Display a manifest to the user:

Found [N] GDDs. Summaries:
  • combat.md — [summary text]
  • inventory.md — [summary text]
  ...

For `since-last-review` mode: run `git log --name-only` to identify GDDs modified since the last review report file was written. Show the user which GDDs are in scope based on summaries before doing any full reads. Only proceed to L1 for those GDDs plus any GDDs listed in their "Key deps".

Phase 1b — Registry Pre-Load (fast baseline)

Before full-reading any GDD, check for the entity registry:

Read path="design/registry/entities.yaml"

If the registry exists and has entries, use it as a **pre-built conflict baseline**: known entities, items, formulas, and constants with their authoritative values and source GDDs. In Phase 2, grep GDDs for registered names first — this is faster than reading all GDDs in full before knowing what to look for.

If the registry is empty or absent: proceed without it. Note in the report: "Entity registry is empty — consistency checks rely on full GDD reads only. Run `/consistency-check` after this review to populate the registry."

Phase 1c — L1/L2: Full Document Load

Full-read the in-scope documents:

1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition 2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars 3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status 4. **Every in-scope system GDD in `design/gdd/`** — read completely (skip game-concept.md and systems-index.md — those are read above)

Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]."

If fewer than 2 system GDDs exist, stop: > "Cross-GDD review requires at least 2 system GDDs. Write more GDDs first, > then re-run `/review-all-gdds`."

---

Parallel Execution

Phase 2 (Consistency) and Phase 3 (Design Theory) are independent — they read the same GDD inputs but produce separate reports. Spawn both as parallel Task agents simultaneously rather than waiting for Phase 2 to complete before starting Phase 3. Collect both results before writing the combined report.

**When spawning parallel Task agents for Phase 2 and Phase 3, always pass:**

• The complete list of GDD file paths loaded in Phase 1 (explicit paths, not just counts)
• The full TR registry contents if loaded in Phase 1b (paste the registry text, not just a file path)
• The specific checklist items assigned to that agent's phase (Phase 2 gets 2a–2f; Phase 3 gets 3a–3g)
• The engine name and version from `.claude/docs/technical-preferences.md` and `docs/engine-reference/[engine]/VERSION.md`

Do not rely on the subagent to re-read these files — it has its own context window and cannot access Phase 1 results unless they are explicitly passed in the Task prompt.

---

Phase 2: Cross-GDD Consistency

Work through every pair and group of GDDs to find contradictions and gaps.

2a: Dependency Bidirectionality

For every GDD's Dependencies section, check that every listed dependency is reciprocal:

• If GDD-A lists "depends on GDD-B", check that GDD-B lists GDD-A as a dependent
• If GDD-A lists "depended on by GDD-C", check that GDD-C lists GDD-A as a dependency
• Flag any one-directional dependency as a consistency issue

⚠️  Dependency Asymmetry
[system-a].md lists: Depends On → [system-b].md
[system-b].md does NOT list [system-a].md as a dependent
→ One of these documents has a stale dependency section

2b: Rule Contradictions

For each game rule, mechanic, or constraint defined in any GDD, check whether any other GDD defines a contradicting rule for the same situation:

Categories to scan:

• **Floor/ceiling rules**: Does any GDD define a minimum value for an output? Does any other say a different system can bypass that floor? These contradict.
• **Resource ownership**: If two GDDs both define how a shared resource accumulates or