review-all-gdds skill

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

Review All GDDs

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

conflicts between documents

1. Cross-GDD Consistency — contradictions, stale references, and ownership

together: dominant strategies, broken economies, cognitive overload, pillar drift, competing progression loops

1. Game Design Holism — issues that only emerge when you see all systems

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

When to run:

inherits those inconsistencies)

• 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

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

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)

workflow per GDD (per .claude/docs/workflow-modes.md): each GDD validates against its effective tier — the project value, overridden per system by the system_overrides row for that system when the block lists one. At full, validate all 8 sections across all GDDs. At standard, validate the 5 required sections; optional sections (Player Fantasy, Tuning Knobs, conditional Formulas) are surfaced as advisory only. At minimal, this skill is not applicable (no GDDs).

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

Fail open on a missing Summary. Establish the denominator: glob design/gdd/.md and count N**. A scan matching fewer than N means those GDDs predate ## Summary — never treat an absent Summary as a system out of scope. A zero-match scan means "no GDD carries a Summary yet", not "nothing to review". This review is holistic and loads its in-scope GDDs regardless (see Phase 1c); the Summary scan only builds the manifest and narrows since-last-review, it never shrinks the review set.

Display a manifest to the user:

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

For since-last-review mode, compute the scope deterministically instead of reasoning through git history:

Bash: bash .claude/scripts/review-scope.sh

It prints PRIORREVIEW:, a CHANGED: list, and a DEPS ...: list of each changed GDD's declared dependencies. Use those lists as the scope — the dependency lines are already the "Key deps" expansion, so no second pass is needed. If PRIORREVIEW: NONE, a full review is required; fall back to full mode.

Show the user which GDDs are in scope based on summaries before doing any full reads. Only proceed to L1 for the CHANGED set plus the GDDs named on the DEPS lines.

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: Section Load

Read whole (small, and every part is used):

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

Then, for every in-scope system GDD, load the sections this review actually consumes — not the whole file:

Grep pattern="^## (Dependencies|Detailed Rules|Detailed Design|Formulas|Tuning Knobs|Acceptance Criteria|Player Fantasy)" glob="design/gdd/*.md" output_mode="content" -A 40

That list is not a guess — it is exactly the union the Parallel Execution contract below already enumerates: Phase 2 needs Dependencies, Detailed Design/Rules, Formulas, Tuning Knobs and Acceptance Criteria; Phase 3 needs Player Fantasy and progression/reward structure. Overview is narrative restated by the Summary this skill already scanned in Phase 1a, and Edge Cases feeds no checklist item here (/design-review owns per-GDD completeness). Loading them put content in three context windows — this one and both sub-agents' — that no checklist item ever read.

Accept either ## Detailed Rules or ## Detailed Design; the design standard and the GDD template disagree on the name and they denote the same section.

Escalate to a full read of one GDD when a scanned section cross-references material outside itself, or when a GDD matched zero sections — that GDD predates the template, and a zero-match there means "unstructured", not "empty". Never let a zero-match silently drop a system: the scan narrows the read, it never shrinks the review set.

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 Agent agents simultaneously rather than waiting for Phase 2 to complete before starting Phase 3. Collect both results before writing the combined report.

Spawn both as game-designer sub-agents (subagent_type: game-designer) — GDD consistency and design-theory review is its domain.

When spawning the Phase 2 and Phase 3 agents, always pass:

sections; the sub-agent has its own context and cannot re-read Phase 1's results, so a path forces a full re-read (and contradicts the "do not re-read" rule below). Pass only the phase's slice: Phase 2 (consistency) needs each GDD's Dependencies, Detailed Design/Rules, Formulas, Tuning Knobs and Acceptance Criteria; Phase 3 (design theory) needs Player Fantasy, progression/reward structure and the game pillars.

• The loaded GDD content each phase needs — not file paths. Paste the

• 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 — engine.name and engine.version from project.yaml, resolving each field independently (if its key is absent or empty, use .claude/docs/technical-preferences.md) — plus 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 Agent 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: