consistency-check

!`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). For `since-last-review` mode: ```bash 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` line. ### 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 REGISTRY** — source GDD value changed but registry not updated. Registry needs updating; other GDDs may be correct already. - **ℹ️ UNVERIFIABLE** — entity mentioned but no comparable attribute stated. Not a conflict; just noting the reference. --- ## Phase 5: Output Report ``` ## Consistency Check Report Date: [date] Registry entries checked: [N entities, N items, N formulas, N constants] GDDs scanned: [N] ([list names]) Scope: [all GDD sections | required sections only — workflow: standard | per GDD — name each GDD whose effective tier differs, and its tier] Not checked at this tier: [each value stated outside the required sections (name, GDD, section) — or "none"; omit when every GDD is at `full`] --- ### Conflicts Found (must resolve before architecture) 🔴 [Entity/Item/Formula/Constant Name] Registry (source: [gdd]): [attribute] = [value] Conflict in [other_gdd].md: [attribute] = [different_value] → Resolution needed: [which doc to change and to what] --- ### Stale Registry Entries (registry behind the GDD) ⚠️ [Entry Name] Registry says: [value] (written [date]) Source GDD now says: [new value] → Update registry entry to match source GDD, then check referenced_by docs. --- ### Unverifiable References (no conflict, informational) ℹ️ [gdd].md mentions [entity_name] but states no comparable attributes. No conflict detected. No action required. --- ### Clean Entries (no issues found) ✅ [N] registry entries verified across all GDDs with no conflicts. --- Verdict: PASS | CONFLICTS FOUND | NOT ASSESSED ``` **Verdict:** - **CONFLICTS FOUND** — one or more conflicts detected. List resolution steps. - **NOT ASSESSED** — nothing was compared: the entity registry is empty or the named entity is not in it (Phase 1), or no GDDs were in scope (Phase 2). Say which. - **PASS** — no conflicts. Registry and GDDs agree on all checked values, across at least one GDD. --- ## Phase 6: Registry Corrections If stale registry entries were found, ask: > "May I update `design/registry/entities.yaml` to fix the [N] stale entries?" For each stale entry: - Update the `value` / attribute field - Set `revised:` to today's date - Add a YAML comment with the old value: `# was: [old_value] before [date]` If new entries were found in GDDs that are not in the registry, ask: > "Found [N] entities/items mentioned in GDDs that aren't in the registry yet. > May I add them to `design/registry/entities.yaml`?" Only add entries that appear in more than one GDD (true cross-system facts). **Never delete registry entries.** Set `status: deprecated` if an entry is removed from all GDDs. After writing: Verdict: **COMPLETE** — consistency check finished. If conflicts remain unresolved: Verdict: **BLOCKED** — [N] conflicts need manual resolution before architecture begins. ### 6b: Append to Reflexion Log If any 🔴 CONFLICT entries were found (regardless of whether they were resolved), ask: "May I append [N] entries to `docs/consistency-failures.md` (creating it if absent)?" On yes, append an entry for each conflict; on no, say the conflicts were not logged. ```markdown ### [YYYY-MM-DD] — /consistency-check — 🔴 CONFLICT **Domain**: [system domain(s) involved] **Documents involved**: [source GDD] vs [conflicting GDD] **What happened**: [specific conflict — entity name, attribute, differing values] **Resolution**: [how it was fixed, or "Unresolved — manual action needed"] **Pattern**: [generalised lesson, e.g. "Item values defined in combat GDD were not referenced in economy GDD before authoring — always check entities.yaml first"] ``` If `docs/consistency-failures.md` does not exist, create it with this header before appending: ```markdown # Consistency Failure Log <!-- Auto-maintained by /consistency-check. Do not edit manually. --> <!-- One entry per detected conflict, in chronological order. --> | Date | GDD A | GDD B | Conflict Type | Status | |------|-------|-------|---------------|--------| ``` Then append the new conflict entries. Never skip logging on your own — a missing file is not a reason to lose conflict history; only the user's "no" is. --- ## Phase 7: Session State and Closing Silently append to `production/session-state/active.md` (create the file if it does not exist): ``` <!-- CONSISTENCY-CHECK: [date] | GDDs checked: [N] | Conflicts found: [N] | Log: docs/consistency-failures.md --> ``` > **Point at `docs/consistency-failures.md` — the file Phase 6 actually appends > to.** A breadcrumb is a pointer left for a future session to follow. One that > names a file nothing writes sends that session looking for conflict history it > will never find, and nothing errors along the way. Never invent a report > filename here. Then close with an `AskUserQuestion` widget: - **Prompt**: "Consistency check complete — [N] conflicts found. What next?" - **Options**: - `[A] Fix the highest-priority conflict now` - `[B] Run /design-review on the most conflicted GDD` - `[C] Stop here` In collaborative and guided modes, never end the skill with plain text — always close with this widget. In autonomous mode, print the findings and recommended next step, then record via `log_decision` (no widget). --- ## Recovery / Reference - **If PASS**: Run `/review-all-gdds` for holistic design-theory review, or `/create-architecture` if all MVP GDDs are complete. - **If CONFLICTS FOUND**: Fix the flagged GDDs, then re-run `/consistency-check` to confirm resolution. - **If STALE REGISTRY**: Update the registry (Phase 6), then re-run to verify. - Run `/consistency-check` after writing each new GDD to catch issues early, not at architecture time.