/consistency-check

name: consistency-check
description: "Scan all GDDs against the entity registry to detect cross-document inconsistencies: same entity with different stats, same item with different values, same formula with different variables. Grep-first approach — reads registry then targets only conflicting GDD sections rather than full document reads."
argument-hint: "[full | since-last-review | entity:<name> | item:<name>]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
model: sonnet

Consistency Check

Detects cross-document inconsistencies by comparing all GDDs against the entity registry (`design/registry/entities.yaml`). Uses a grep-first approach: reads the registry once, then targets only the GDD sections that mention registered names — no full document reads unless a conflict needs investigation.

**This skill is the write-time safety net.** It catches what `/design-system`'s per-section checks may have missed and what `/review-all-gdds`'s holistic review catches too late.

**When to run:**

• After writing each new GDD (before moving to the next system)
• Before `/review-all-gdds` (so that skill starts with a clean baseline)
• Before `/create-architecture` (inconsistencies poison downstream ADRs)
• On demand: `/consistency-check entity:[name]` to check one entity specifically

**Output:** Conflict report + optional registry corrections

---

Phase 1: Parse Arguments and Load Registry

**Modes:**

• No argument / `full` — check all registered entries against all GDDs
• `since-last-review` — check only GDDs modified since the last review report
• `entity:<name>` — check one specific entity across all GDDs
• `item:<name>` — check one specific item across all GDDs

**Load the registry:**

Read path="design/registry/entities.yaml"

If the file does not exist or has no entries: > "Entity registry is empty. Run `/design-system` to write GDDs — the registry > is populated automatically after each GDD is completed. Nothing to check yet."

Stop and exit.

Build four lookup tables from the registry:

• **entity_map**: `{ name → { source, attributes, referenced_by } }`
• **item_map**: `{ name → { source, value_gold, weight, ... } }`
• **formula_map**: `{ name → { source, variables, output_range } }`
• **constant_map**: `{ name → { source, value, unit } }`

Count total registered entries. Report:

Registry loaded: [N] entities, [N] items, [N] formulas, [N] constants
Scope: [full | since-last-review | entity:name]

---

Phase 2: Locate In-Scope GDDs

Glob pattern="design/gdd/*.md"

Exclude: `game-concept.md`, `systems-index.md`, `game-pillars.md` — these are not system GDDs.

For `since-last-review` mode:

git log --name-only --pretty=format: -- design/gdd/ | grep "\.md$" | sort -u

Limit to GDDs modified since the most recent `design/gdd/gdd-cross-review-*.md` file's creation date.

Report the in-scope GDD list before scanning.

---

Phase 3: Grep-First Conflict Scan

For each registered entry, grep every in-scope GDD for the entry's name. Do NOT do full reads — extract only the matching lines and their immediate context (-C 3 lines).

This is the core optimization: instead of reading 10 GDDs × 400 lines each (4,000 lines), you grep 50 entity names × 10 GDDs (50 targeted searches, each returning ~10 lines on a hit).

3a: Entity Scan

For each entity in entity_map:

Grep pattern="[entity_name]" glob="design/gdd/*.md" output_mode="content" -C 3

For each GDD hit, extract the values mentioned near the entity name:

• any numeric attributes (counts, costs, durations, ranges, rates)
• any categorical attributes (types, tiers, categories)
• any derived values (totals, outputs, results)
• any other attributes registered in entity_map

Compare extracted values against the registry entry.

**Conflict detection:**

• Registry says `[entity_name].[attribute] = [value_A]`. GDD says `[entity_name] has [value_B]`. → **CONFLICT**
• Registry says `[item_name].[attribute] = [value_A]`. GDD says `[item_name] is [value_B]`. → **CONFLICT**
• GDD mentions `[entity_name]` but doesn't specify the attribute. → **NOTE** (no conflict, just unverifiable)

3b: Item Scan

For each item in item_map, grep all GDDs for the item name. Extract:

• sell price / value / gold value
• weight
• stack rules (stackable / non-stackable)
• category

Compare against registry entry values.

3c: Formula Scan

For each formula in formula_map, grep all GDDs for the formula name. Extract:

• variable names mentioned near the formula
• output range or cap values mentioned

Compare against registry entry:

• Different variable names → **CONFLICT**
• Output range stated differently → **CONFLICT**

3d: Constant Scan

For each constant in constant_map, grep all GDDs for the constant name. Extract:

• Any numeric value mentioned near the constant name

Compare against registry value:

• Different number → **CONFLICT**

---

Phase 4: Deep Investigation (Conflicts Only)

For each conflict found in Phase 3, do a targeted full-section read of the conflicting GDD to get precise context:

Read path="design/gdd/[conflicting_gdd].md"

(Or use Grep with wider context if the file is large)

Confirm the conflict with full context. Determine: 1. **Which GDD is correct?** Check the `source:` field in the registry — the source GDD is the authoritative owner. Any other GDD that contradicts it is the one that needs updating. 2. **Is the registry itself out of date?** If the source GDD was updated after the registry entry was written (check git log), the registry may be stale. 3. **Is this a genuine design change?** If the conflict represents an intentional design decision, the resolution is: update the source GDD, update the registry, then fix all other GDDs.

For each conflict, classify:

• **🔴 CONFLICT** — same named entity/item/formula/constant with different values

in different GDDs. Must resolve before architecture begins.

• **⚠️ STALE