/consistency-check

name: consistency-check
description: "Scan GDDs against the entity registry for cross-document conflicts. Grep-first approach targets conflicting sections, different stats."
argument-hint: "[full | since-last-review | entity:<name> | item:<name>]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Bash(bash "*/.claude/skills/consistency-check/../../hooks/yaml-helper.sh" resolve_config *), Bash(git log *), Bash(bash .claude/scripts/registry.sh validate*)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,system_overrides`

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

---

Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

**`workflow`** (see `.claude/docs/workflow-modes.md`), applied per GDD at its **effective** tier — the `system_overrides` row for that GDD's system (its filename stem) when the block lists one, else the project value:

• `full` — full entity-registry cross-check against all GDD sections.
• `standard` — cross-check against the required sections only. The report's

Scope line says so, and each value stated for a registered name outside those sections is listed as not checked at this tier (Phase 3 applies this).

• `minimal` — not meaningful (no GDDs to check).

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."

Verdict: **NOT ASSESSED — entity registry empty**. Stop: nothing was compared, so there is no PASS to give and nothing to write.

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]

For `entity:<name>` or `item:<name>`, if the registry has no entry by that name the verdict is **NOT ASSESSED — `<name>` is not in the registry**: list the closest registered names and stop. Checking an unregistered name compares nothing, and that is not a PASS.

---

Phase 2: Locate In-Scope GDDs

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

Exclude the docs that live in `design/gdd/` but are not system GDDs: `game-concept.md`, `systems-index.md`, `game-pillars.md`, `gameplay-tags.md`, `entity-registry.md`, `fixture-swap-ledger.md`, `sound-bible.md` and any `gdd-cross-review-*.md` (the report `/review-all-gdds` writes here). The entity registry itself is `design/registry/entities.yaml`, outside this glob.

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. **If the list is empty** — no system GDDs exist, or `since-last-review` found none changed — the verdict is **NOT ASSESSED — no GDDs in scope**: say which filter produced zero, and stop. A scan of nothing finds no conflicts, and that is not a PASS.

---

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).

**In a GDD whose effective tier is `standard`, compare only hits under a required section.** The effective tier is per GDD: `system_overrides.<stem>` replaces the project tier for that GDD in either direction (a `full` row makes every section compared). Grep each such GDD once for `^## ` to get its headings and line numbers, and file every name hit under the nearest heading above it: only hits under Overview, Detailed Rules / Detailed Design, Formulas, Edge Cases, Dependencies or Acceptance Criteria are compared — plus Tuning Knobs when `project.yaml` sets `workflow_overrides.tuning_knobs: true` (read that flag once; it only ever adds the section). Any other hit (Tuning Knobs without the flag, Player Fantasy, any other section) raises no finding and is not logged; list each one that states a value (name, GDD, section) on the report's `Not checked at this tier