Review All GDDs

Review All GDDs

What Is This

The "Review All GDDs" skill (review-all-gdds) is an advanced design review utility for the Happycapy Skills platform. It performs a holistic, cross-document analysis of all Game Design Documents (GDDs) within a project. Unlike single-document review tools, this skill reads every system GDD simultaneously to identify inter-document contradictions, stale references, overlapping responsibilities, formula incompatibilities, and violations of foundational game design theory. Its analysis scope includes both technical consistency and design holism, making it an essential step before architectural planning or major production phases.

This skill distinguishes itself from single-GDD reviews (such as /design-review) by focusing on relationships and systemic issues that only emerge when evaluating the complete design landscape. It is optimized for projects that have reached a minimum viable product (MVP) stage in their GDDs and require rigorous pre-architecture validation.

Why Use It

Relying on per-GDD checks can leave major design flaws undetected. Game systems rarely exist in isolation. When multiple designers or teams contribute GDDs, inconsistencies, overlapping ownership, and emergent design problems are common. Failing to address these issues before moving to architecture can result in expensive refactoring, game balance issues, or even failed game loops.

Key reasons to use "Review All GDDs":

• Cross-GDD Consistency: Ensures all documents reference each other correctly, catch contradictions (e.g., two systems claiming authority over the same data), and flag stale or broken references.
• Ownership Conflict Detection: Identifies when multiple GDDs declare responsibility for the same mechanic, feature, or resource.
• Formula and Data Compatibility Checks: Verifies that formulas and data types are compatible across systems (e.g., currency values, health calculations).
• Game Design Theory Validation: Detects dominant strategies, economic imbalances, cognitive overload, pillar drift, and competing progression loops that only surface when viewing all systems together.
• Reliable Foundation for Architecture: Guarantees that subsequent engineering phases are built on a clean, coherent design base.

How to Use It

The skill is user-invocable and provides several argument modes to tailor the review focus. Invocation can be performed via the Happycapy command interface (CLI or integrated tools).

Basic Usage Example:

/review-all-gdds full

Argument Modes:

• full: Runs both cross-GDD consistency and design holism checks.
• consistency: Checks only for contradictions, stale references, ownership conflicts, and formula compatibility.
• design-theory: Focuses on game design theory errors like dominant strategies, economic imbalances, and pillar drift.
• since-last-review: Limits the review to changes made since the previous invocation, improving efficiency for large projects.

Code Example for Integration:

If integrating within a CI pipeline or as a pre-architecture gate, a sample YAML task might look like:

- name: Cross-GDD Review
  run: |
    review-all-gdds full
  env:
    GDD_ROOT: ./gdd/

The skill leverages tools such as Read, Glob, Grep, and Bash for document access and parsing, ensuring that all relevant GDD files are considered in the analysis.

When to Use It

The optimal times to invoke "Review All GDDs" are:

• After All MVP GDDs Are Approved: Once each system's GDD passes individual review, run this skill before any technical architecture begins.
• After Major GDD Revisions: If any GDD undergoes substantial change mid-production, rerun the review to verify that system-wide consistency and balance are maintained.
• Before Architecture Creation: Always run this skill as a final gate before /create-architecture. Building technical architecture on inconsistent or unbalanced design leads to downstream issues that are much harder to correct.

Important Notes

• Distinct from Single-GDD Review: This skill does not check for internal completeness within a single GDD. Use /design-review for per-document validation.
• Requires All GDDs: The review is only meaningful when all system GDDs are present and complete. Running it with missing or placeholder GDDs may yield false positives or incomplete analysis.
• Argument Focus Matters: Choose the appropriate argument mode for the project's needs. For full production gates, full is recommended. For iterative work, since-last-review saves time.
• Not a Substitute for Human Oversight: The skill automates many consistency and theory checks, but nuanced design issues may still require human judgment and follow-up discussion.
• Impact on Project Flow: Addressing issues identified by this review is critical before architecture work begins. Ignoring or bypassing the findings can lead to costly rework and design drift.

By incorporating "Review All GDDs" at key milestones, teams can ensure that their game designs are robust, internally coherent, and ready for implementation. This approach reduces risk, improves production efficiency, and supports the delivery of a well-balanced, engaging game experience.