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.
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:
/review-all-gdds (so that skill starts with a clean baseline)/create-architecture (inconsistencies poison downstream ADRs)/consistency-check entity:[name] to check one entity specificallyOutput: Conflict report + optional registry corrections
Modes:
full — check all registered entries against all GDDssince-last-review — check only GDDs modified since the last review reportentity:<name> — check one specific entity across all GDDsitem:<name> — check one specific item across all GDDsLoad the registry:
Read path="design/registry/entities.yaml"
If the file does not exist or has no entries:
"Entity registry is empty. Run
/design-systemto 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:
{ name → { source, attributes, referenced_by } }{ name → { source, value_gold, weight, ... } }{ name → { source, variables, output_range } }{ 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]
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.
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).
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:
Compare extracted values against the registry entry.
Conflict detection:
[entity_name].[attribute] = [value_A]. GDD says [entity_name] has [value_B]. → CONFLICT[item_name].[attribute] = [value_A]. GDD says [item_name] is [value_B]. → CONFLICT[entity_name] but doesn't specify the attribute. → NOTE (no conflict, just unverifiable)For each item in item_map, grep all GDDs for the item name. Extract:
Compare against registry entry values.
For each formula in formula_map, grep all GDDs for the formula name. Extract:
Compare against registry entry:
For each constant in constant_map, grep all GDDs for the constant name. Extract:
Compare against registry value:
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:
source: field in the registry — the
source GDD is the authoritative owner. Any other GDD that contradicts it
is the one that needs updating.For each conflict, classify:
## Consistency Check Report
Date: [date]
Registry entries checked: [N entities, N items, N formulas, N constants]
GDDs scanned: [N] ([list names])
---
### 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
Verdict:
If stale registry entries were found, ask:
"May I update
design/registry/entities.yamlto fix the [N] stale entries?"
For each stale entry:
value / attribute fieldrevised: to today's date# 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.
If any 🔴 CONFLICT entries were found (regardless of whether they were resolved),
append an entry to docs/consistency-failures.md for each conflict:
### [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"]
Only append if docs/consistency-failures.md exists. If the file is missing,
skip this step silently — do not create the file from this skill.
/review-all-gdds for holistic design-theory review, or
/create-architecture if all MVP GDDs are complete./consistency-check to confirm resolution./consistency-check after writing each new GDD to catch issues early,
not at architecture time.