Consistency Check

Consistency Check Skill for Happycapy Skills Platform

What Is This

The Consistency Check skill (consistency-check) is a cross-document validation tool designed for the Happycapy Skills platform, aimed at ensuring data integrity across Game Design Documents (GDDs). It operates by scanning all GDDs and comparing their content against a centralized entity registry (design/registry/entities.yaml). The skill detects inconsistencies in entity definitions, item values, and formulas across different documents. Its purpose is to serve as an efficient and effective safety net, identifying potential issues at the time of writing, rather than after inconsistencies have propagated through the design process.

The core mechanism of this skill is a grep-first approach. Instead of reading entire documents, it first reads the registry and then targets only those GDD sections that reference registered names. Full document reads are performed only if a conflict is detected and further investigation is necessary. This targeted scanning methodology results in significant performance improvements, especially in large projects with expansive design documentation.

Why Use It

Maintaining consistency across multiple GDDs is a common pain point in collaborative game development. Divergent stats for the same entity, conflicting item values, or mismatched formula variables can result in design errors that are expensive to fix later. Manual checking is tedious and error-prone, while traditional holistic review tools only catch these problems late in the pipeline.

The Consistency Check skill provides several advantages:

• Early Detection: Catches inconsistencies immediately after writing, minimizing the risk of propagation.
• Granularity: Ability to target specific entities or items for auditing, reducing noise and focusing review efforts.
• Automation: Reduces manual review workload by automating cross-document checks.
• Registry-Driven: Ensures that the centralized entity registry remains the single source of truth, simplifying maintenance and onboarding for new team members.
• Performance: The grep-first scanning method avoids unnecessary reads, ensuring the tool remains responsive even as the project grows.

How to Use It

The Consistency Check skill is user-invocable and can be run with several argument modes to tailor its operation:

Argument Syntax

/consistency-check [full | since-last-review | entity:<name> | item:<name>]

• full or no argument: Checks all registered entries (entities, items, formulas) against every GDD.
• since-last-review: Scans only those documents or sections modified since the last review.
• entity:<name>: Targets a specific entity by name for a focused check.
• item:<name>: Targets a specific item by name for a focused check.

Example Usage

To check for all inconsistencies across all GDDs:

/consistency-check full

To check if the entity "Goblin" has conflicting stats:

/consistency-check entity:Goblin

Core Workflow

1. Parse Arguments and Load Registry:

   • The skill parses the provided arguments to determine the scope.
   • Loads the central registry (design/registry/entities.yaml) to obtain authoritative values.

2. Targeted Grep:

   • Searches all GDDs for references to registered entities/items.
   • Only reads and analyzes sections containing relevant names.

3. Inconsistency Detection:

   • Compares the values (e.g., stats, names, formulas) found in GDDs with the registry.
   • Flags any mismatches, such as different health values for "Goblin" in different documents.

4. Reporting:

   • Generates a conflict report listing all detected inconsistencies.
   • Optionally suggests registry corrections or highlights sections needing manual intervention.

Pseudocode Example

## Bash pseudocode for targeted check
grep -rnw "design/docs/" -e "Goblin" | while read -r line; do
  # Extract values and compare with registry
  if [ "$doc_stat" != "$registry_stat" ]; then
    echo "Conflict: Goblin stat mismatch in $line"
  fi
done

When to Use It

The Consistency Check skill is designed for use at several critical points within the workflow:

• After writing each new GDD: Identify errors before moving on to additional systems.
• Before running a holistic review (/review-all-gdds): Ensure reviews start from a clean, consistent baseline.
• Before architecture creation (/create-architecture): Avoid propagating design inconsistencies into architecture decision records (ADRs).
• On demand: Run targeted checks for specific entities or items whenever a focused review is required.

Important Notes

• This skill is intended as a write-time safety net. It is not a substitute for comprehensive design review but complements other tools and processes.
• Registry-driven validation means all entities and items must be accurately maintained in entities.yaml for checks to be effective.
• The skill relies on the grep utility and standard text processing tools (Read, Glob, Grep, Write, Edit, Bash). Ensure your environment supports these operations.
• In case of conflicts, the skill does not automatically resolve them. Manual intervention is required to correct either the registry or the conflicting GDD sections.
• The skill is optimized for projects using a structured registry. Projects lacking a centralized registry may experience reduced effectiveness.

By integrating the Consistency Check skill into your workflow, you can significantly reduce cross-document inconsistencies, resulting in cleaner, more maintainable, and more reliable game design documentation.