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

> Streamline GDDs at Claude-Code Game Studios. Use the /design-review skill for individual documents and /review-all-gdds for cross-document consistency checks. Boost your game dev workflow today.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/design-review/SKILL.md) and [`.claude/skills/review-all-gdds/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/review-all-gdds/SKILL.md) respectively, and integrate into the workflow gates described in [`docs/WORKFLOW-GUIDE.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/design/gdd/combat-system.md)). The [`design/gdd/systems-index.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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:

```bash
/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:

```bash
/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/combat-system.md) declares dependency on [`inventory-system.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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:

```bash
/gate-check systems-design

```

According to the workflow guide in [`docs/WORKFLOW-GUIDE.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/WORKFLOW-GUIDE.md) | Documents the integration of review skills into the 7-phase pipeline and gate-check requirements. |
| [`design/gdd/systems-index.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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.