Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/review/review-all-gdds.md

Skill Test Spec: /review-all-gdds

Skill Summary

/review-all-gdds is an Opus-tier skill that performs a holistic cross-GDD review across the system GDDs in design/gdd/. After loading everything (Phase 1), it runs two independent reviews in parallel as game-designer sub-agents: Phase 2, Cross-GDD Consistency (dependency bidirectionality, rule contradictions, stale references, ownership conflicts, formula compatibility, acceptance-criteria conflicts), and Phase 3, Game Design Holism (competing progression loops, attention budget, dominant strategies, economic loops, difficulty curves, pillar alignment, player-fantasy coherence). Phase 4 walks multi-system scenarios. It produces a PASS / NOT ASSESSED / CONCERNS / FAIL verdict, and writes design/gdd/gdd-cross-review-[YYYY-MM-DD].md and systems-index "Needs Revision" statuses only after the user approves.

It is invoked after individual GDDs are approved and before architecture work. It spawns no director gate agents. At workflow: minimal it does not apply (no GDDs), so every fixture below sets modes.workflow: full.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥5 phase headings (complex multi-phase skill)
• Contains verdict keywords: PASS, NOT ASSESSED, CONCERNS, FAIL
• allowed-tools includes Write, so "May I write" language is present (Phase 6 report write)
• Has a next-step handoff at the end
• Documents parallel spawning of Phase 2 (Consistency) and Phase 3 (Design Theory)

---

Director Gate Checks

No director gates — this skill spawns no director gate agents and resolves no review mode. It IS the holistic review; its only agents are the two game-designer sub-agents for Phases 2 and 3.

---

Test Cases

Case 1: Happy Path — Clean GDD set with no conflicts

Fixture:

• project.yaml sets modes.workflow: full
• design/gdd/ contains game-concept.md, game-pillars.md (pillars and anti-pillars), systems-index.md, and three system GDDs — combat.md, inventory.md, crafting.md — each with every section Phase 1c loads and a filled ## Cross-References table whose rows all resolve
• All GDDs are consistent: no formula contradictions, no competing ownership, no stale references, reciprocal dependencies; every system serves a pillar
• Nothing a design-theory check would warn on either: one primary progression loop, at most 4 systems active at once, every resource has both a source and a sink, compatible scaling curves, compatible player fantasies

Input: /review-all-gdds

Expected behavior:

1. Skill greps ## Summary across design/gdd/*.md and shows a manifest ("Found [N] GDDs. Summaries: …")
2. Skill reads the entity registry, or notes that it is empty and suggests /consistency-check
3. Skill loads the review sections and reports "Loaded [N] system GDDs covering [M] systems. Pillars: […]. Anti-pillars: […]."
4. Phase 2 and Phase 3 spawn simultaneously as game-designer sub-agents, each given the pasted GDD content for its slice (not file paths) and its checklist (2a–2f / 3a–3g)
5. Phase 4 walks 3–5 multi-system scenarios
6. Report shows no blocking issues and no warnings; verdict PASS
7. AskUserQuestion: "May I write this review to design/gdd/gdd-cross-review-[date].md?"
8. Closing widget built from project state

Assertions:

• Phase 2 and Phase 3 are spawned in parallel (both Agent calls issued before either result is awaited)
• Sub-agent prompts carry the GDD section content, not just file paths
• The report states the covered set: GDDs reviewed: [N] of [M] present and Not read: none, and lists the scenarios walked
• Verdict is PASS only because there are no blocking issues and no warnings, over three readable GDDs — a single warning would make it CONCERNS
• The report is written only after the user approves, under an ISO-dated name (gdd-cross-review-YYYY-MM-DD.md)
• The closing widget offers /create-architecture and /gate-check (both allowed on PASS)

---

Case 2: Failure Path — Conflicting rules between two GDDs

Fixture:

• project.yaml sets modes.workflow: full
• combat.md defines a floor: "Minimum damage after armour reduction is 1"
• status-effects.md states a mechanic that bypasses it: "Poison ignores armour and can reduce damage to 0"
• The two GDDs are otherwise complete and valid; game-pillars.md defines the pillars and systems-index.md lists both systems

Input: /review-all-gdds

Expected behavior:

1. Phase 2 detects the floor/ceiling contradiction
2. Report prints a 🔴 Rule Contradiction entry quoting both rules and asking which GDD is authoritative
3. The issue sits under Consistency Issues → Blocking; both GDDs appear in "GDDs Flagged for Revision"
4. Verdict: FAIL, with "If FAIL — required actions before re-running"
5. After the report write question, a second AskUserQuestion offers to mark the flagged GDDs Needs Revision in systems-index.md

Assertions:

• Verdict is FAIL (not PASS, CONCERNS or NOT ASSESSED)
• Both GDD filenames are named in the conflict entry
• The specific contradicting rules are quoted (not a vague "conflict found")
• The issue is classified as Blocking (🔴), and both GDDs are in the flagged table with Priority Blocking
• Skill does NOT decide which GDD is right and does NOT edit either GDD
• If the user approves the systems-index update, the status is written as exactly Needs Revision with no parenthetical
• The closing widget offers neither /create-architecture nor /gate-check (verdict is FAIL)

---

Case 3: Partial Path — Cross-reference to a GDD that does not exist

Fixture:

• project.yaml sets modes.workflow: full
• design/gdd/ holds game-pillars.md, systems-index.md and two consistent system GDDs, crafting.md and inventory.md
• crafting.md's ## Cross-References table has a row whose Target GDD is system-b.md; no design/gdd/system-b.md exists
• systems-index.md lists system-b as the next system with Status: Not Started
• Nothing else would warn

Input: /review-all-gdds

Expected behavior:

1. Phase 2's stale-reference check (2c) confirms each Cross-References row's Target GDD exists, and finds system-b.md missing
2. Because systems-index.md lists system-b, the reference is a dependency on planned work: a ⚠️ Stale Reference Warning naming crafting.md and the missing target, to re-check when that GDD is written
3. No other issues found; verdict CONCERNS (warnings, nothing blocking)
4. Closing widget includes /design-system system-b (next in design order)

Assertions:

• The finding names crafting.md and the missing system-b.md
• It is reported under Warnings (⚠️), not Blocking — because the systems index lists system-b as planned
• Verdict is CONCERNS — not FAIL for a reference to planned work, and not an unqualified PASS
• The closing widget offers /design-system system-b, and offers /create-architecture but not /gate-check (which requires PASS)
• Skill does NOT skip or silently ignore the missing target

Case 3b — the target is in neither place: the same fixture, except systems-index.md has no entry for system-b. Nothing will ever define it.

Assertions (3b):

• The reference is reported as 🔴 Blocking, and crafting.md appears in "GDDs Flagged for Revision" with Priority Blocking
• Verdict is FAIL, and the closing widget offers neither /create-architecture nor /gate-check

---

Case 4: Edge Case — Fewer than two system GDDs

Fixture:

• project.yaml sets modes.workflow: full
• design/gdd/ contains systems-index.md and a single system GDD, combat.md

Input: /review-all-gdds

Expected behavior:

1. Skill loads what exists and counts the system GDDs
2. Fewer than 2 → skill stops with: "Cross-GDD review requires at least 2 system GDDs. Write more GDDs first, then re-run /review-all-gdds."
3. No review phase runs and no report is offered

Assertions:

• Skill outputs the "requires at least 2 system GDDs" stop message
• Neither Phase 2 nor Phase 3 sub-agent is spawned
• No verdict of PASS is produced for the single document
• No report write is offered and no file is written

---

Case 5: Director Gate — none spawned, whatever the review mode

Fixture:

• project.yaml sets modes.workflow: full
• design/gdd/ holds the Case 1 set: concept, pillars, systems index and three consistent system GDDs
• 5a: modes.review_mode: full; 5b: modes.review_mode: solo

Input: /review-all-gdds

Expected behavior:

1. The resolved config block requests only automation, workflow and system_overrides — review mode is not consulted
2. In both 5a and 5b, the same two game-designer sub-agents run Phases 2 and 3
3. No director gate agent is spawned; the verdict is produced normally

Assertions:

• No director gate agents (CD-, TD-, PR-, AD-, LP- prefixed gates) are spawned in either mode
• Review mode changes nothing: under solo the two game-designer sub-agents still run
• Output contains no "Gate: [GATE-ID]" or "[GATE-ID] skipped" entries
• The skill produces a verdict in both modes
• The only Agent spawns in the run are the Phase 2 and Phase 3 game-designer sub-agents

---

Case 6: NOT ASSESSED — fewer than two readable GDDs

Fixture:

• project.yaml sets modes.workflow: full
• design/gdd/ holds game-pillars.md, systems-index.md and two system GDDs: combat.md, complete, and inventory.md, which has the template's headings but only placeholder text under them

Input: /review-all-gdds

Expected behavior:

1. Two system GDDs exist, so the "requires at least 2 system GDDs" stop does not fire
2. inventory.md is present but empty — not reviewable — so only one GDD can be compared, and a clean result would mean only that nothing was compared
3. Verdict NOT ASSESSED; "If NOT ASSESSED — what could not be reviewed, and why" names inventory.md as placeholder-only and says a cross-review needs two readable GDDs
4. The report states GDDs reviewed: 1 of 2 present

Assertions:

• Verdict is NOT ASSESSED — not PASS, although no contradiction was found
• The report names inventory.md as present but not reviewable, and states GDDs reviewed: 1 of 2 present
• A GDD that could not be read at all would be named on the report's Not read: line under every verdict, and is a NOT ASSESSED trigger like an empty one
• The closing widget offers neither /create-architecture nor /gate-check

---

Protocol Compliance

• Phase 2 (Consistency) and Phase 3 (Design Theory) spawned in parallel — not sequentially
• The full analysis is shown before any write is requested
• Does NOT write the report or update systems-index.md without AskUserQuestion approval
• Verdict is one of exactly: PASS, NOT ASSESSED, CONCERNS, FAIL
• Every issue cites the GDD, section and text involved
• Ends with an AskUserQuestion handoff built from the verdict: FAIL or NOT ASSESSED → neither /create-architecture nor /gate-check; CONCERNS → /create-architecture only; PASS → both

---

Coverage Notes

• Economic loop analysis (3d, source/sink loops) is not fixture-tested. Case 2 exercises Phase 2's rule-contradiction check — a different checklist, run by the other sub-agent — so it says nothing about 3d.
• The design theory phase (Phase 3) checks, including dominant strategy detection and cognitive overload, are not individually fixture-tested.
• Case 6 covers the fewer-than-two-readable-GDDs trigger, through a present-but-empty GDD. The NOT ASSESSED triggers for undefined pillars and for a sub-agent that returns no report are not fixture-tested.
• The since-last-review mode (.claude/scripts/review-scope.sh) and the consistency / design-theory focus modes are not tested here.