How to Run Design Reviews and Consistency Checks on GDDs in Claude-Code Game Studios

Use the /design-review skill for individual GDD validation and /review-all-gdds for cross-document consistency checks in the Claude-Code Game Studios framework.

The Claude-Code Game Studios repository provides dedicated automation skills to validate Game Design Documents (GDDs) before implementation begins. These tools ensure your design documentation is both complete and coherent, dramatically reducing rework later in the development pipeline.

Understanding the Review Skills

The framework provides two distinct user-invocable skills for running design reviews and consistency checks on GDDs:

Goal	Skill	Function
Individual GDD review	/design-review	Validates a single document against the 8-section standard, checking internal logic, dependencies, and acceptance criteria.
Cross-GDD consistency	/review-all-gdds	Evaluates all system GDDs together to catch contradictions, stale references, pillar drift, and dominant-strategy risks across the entire design.

Both skills are defined in .claude/skills/design-review/SKILL.md and .claude/skills/review-all-gdds/SKILL.md respectively, and integrate into the workflow gates described in docs/WORKFLOW-GUIDE.md.

Running Individual Design Reviews

Prerequisites

Before executing a design review, ensure your GDD follows the repository structure. Place each system's document under design/gdd/ (for example, design/gdd/combat-system.md). The design/gdd/systems-index.md file should list the status of every GDD to ensure the review tools can locate dependencies.

Executing the Review

Run the skill by passing the path to your GDD:

/design-review design/gdd/combat-system.md

The skill reads the target GDD, the game concept document, and any referenced documents. It validates completeness against the 8-section standard and analyses internal logic, dependency graphs, and acceptance criteria.

Interpreting Results

The skill returns one of three verdicts:

• APPROVED — The GDD meets all standards and is ready for cross-GDD review.
• NEEDS REVISION — Minor issues detected; fix flagged items and re-run.
• MAJOR REVISION NEEDED — Critical gaps or contradictions require significant rework before proceeding.

Typical output includes section completeness scores (for example, "7/8 sections present") and dependency status (listing which referenced documents exist or are missing).

Running Cross-GDD Consistency Checks

Once all individual MVP GDDs achieve APPROVED status, run the comprehensive consistency check to validate the entire design corpus.

Phase 1: Dependency Manifest

Execute the cross-review command:

/review-all-gdds

The skill first loads every GDD from design/gdd/ and produces a manifest of discovered documents. It validates file naming conventions and ensures the systems-index.md is synchronized with actual files on disk.

Phase 2: Consistency Validation

The skill executes bidirectional dependency checks to detect asymmetries (for example, if combat-system.md declares dependency on inventory-system.md, but the inventory system does not list combat as a dependent). It also validates:

• Rule contradictions — Conflicting parameter definitions across systems.
• Stale references — Links to deprecated mechanics or non-existent GDDs.
• Ownership conflicts — Multiple systems claiming authority over the same gameplay element.
• Formula compatibility — Mathematical ranges that don't align (for example, movement speed capped at 12 m/s while combat damage scaling expects 0–8 m/s).
• Acceptance-criteria cross-checks — Ensuring integration tests defined in one GDD are supported by mechanics in dependent systems.

Phase 3: Design Theory Analysis

Beyond technical consistency, the skill runs holistic design-theory checks including:

• Competing progression loops — Detecting when multiple systems award XP as the primary incentive, creating cognitive load.
• Dominant strategy risks — Identifying mechanics that could trivialize other systems.
• Economic balance — Cross-referencing currency faucets and drains across systems.
• Difficulty-curve consistency — Ensuring challenge progression aligns across combat, movement, and progression systems.
• Pillar/anti-pillar alignment — Verifying mechanics support the game's core design pillars rather than contradicting them.
• Player-fantasy coherence — Checking that system behaviors align with the promised player experience.

Reviewing the Output Report

The skill writes a consolidated report to design/gdd/gdd-cross-review-<date>.md. The report categorizes findings as:

• Blocking — Must be resolved before architecture phase begins.
• Warning — Should be addressed but doesn't block progress.
• Info — Observations for design consideration.

The final verdict is PASS, CONCERNS, or FAIL, indicating whether the design corpus is ready for the Systems-Design gate.

Passing the Systems-Design Gate

After achieving APPROVED status on all individual GDDs and a PASS (or CONCERNS with acknowledged risks) verdict from the cross-review, validate the phase completion:

/gate-check systems-design

According to the workflow guide in docs/WORKFLOW-GUIDE.md, this gate verifies that all MVP GDDs are approved and the cross-review report exists with an acceptable verdict. Passing this gate advances the pipeline to the Technical Setup phase.

Key Files and Implementation Details

Understanding the underlying skill definitions helps customize the review process:

File	Purpose
.claude/skills/design-review/SKILL.md	Defines the individual GDD review workflow, required 8-section standard, and output format including verdict categories.
.claude/skills/review-all-gdds/SKILL.md	Implements the three-phase validation (consistency, design theory, report generation) and defines blocking vs. warning criteria.
docs/WORKFLOW-GUIDE.md	Documents the integration of review skills into the 7-phase pipeline and gate-check requirements.
design/gdd/systems-index.md	Master registry of systems; reviewed by both skills to ensure completeness.
design/gdd/gdd-cross-review-*.md	Auto-generated output from /review-all-gdds; consumed by gate-checks and architecture phases.

Summary

• Use /design-review to validate individual GDDs against the 8-section standard and catch internal inconsistencies before they affect other systems.
• Use /review-all-gdds to execute comprehensive cross-document consistency checks and holistic design-theory analysis across your entire game design corpus.
• Address Blocking findings immediately to prevent architecture-phase rework; resolve Warnings to reduce technical debt.
• Pass the systems-design gate only when all individual reviews show APPROVED and the cross-review report shows PASS or acknowledged CONCERNS.

Frequently Asked Questions

What is the difference between /design-review and /review-all-gdds?

The /design-review skill examines a single GDD for internal completeness, checking that all 8 required sections are present, dependencies are valid, and acceptance criteria are clear. The /review-all-gdds skill evaluates the entire GDD corpus together, detecting cross-system contradictions, stale references, and holistic design issues like dominant strategies or competing progression loops.

Where are the review reports saved?

Individual design reviews output their verdict directly in the conversation. The cross-GDD consistency check generates a markdown file at design/gdd/gdd-cross-review-<date>.md, where <date> is the ISO date of the review. This file contains the full Phase 1-3 analysis and the final verdict.

Can I run a design review on a GDD that is still in draft status?

Yes, running /design-review on draft GDDs is encouraged during development to catch structural issues early. However, the systems-design gate check requires all MVP GDDs to reach APPROVED status, so draft documents must be finalized and approved before passing the gate.

What happens if the cross-GDD review finds Blocking issues?

Blocking issues must be resolved before the architecture phase begins. Edit the relevant GDDs to fix the contradictions, missing dependencies, or rule conflicts flagged in the report, then re-run /review-all-gdds to generate a new report. Only PASS or acknowledged CONCERNS verdicts allow progression through the systems-design gate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}