consistency-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

通过将所有GDD与实体注册表（

design/registry/entities.yaml

）进行比对，检测跨文档不一致问题。采用优先grep的方法：仅读取一次注册表，然后仅针对提及已注册名称的GDD部分进行检查——除非需要调查冲突，否则不会读取完整文档。

此技能是编写阶段的安全保障。 它能捕捉到

/design-system

的逐节检查可能遗漏的问题，以及

/review-all-gdds

的整体检查发现过晚的问题。

运行时机：

编写完每个新GDD之后（在开始下一个系统之前）
运行
```
/review-all-gdds
```
之前（以便该技能从干净的基线开始检查）
运行
```
/create-architecture
```
之前（不一致问题会对下游ADR造成不良影响）
按需运行：
```
/consistency-check entity:[name]
```
专门检查单个实体

输出： 冲突报告 + 可选的注册表修正

Phase 1: Parse Arguments and Load Registry

阶段1：解析参数并加载注册表

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]

模式：

无参数 /
```
full
```
—— 检查所有已注册条目与所有GDD的一致性
```
since-last-review
```
—— 仅检查自上次审查报告后修改过的GDD
```
entity:<name>
```
—— 专门检查单个实体在所有GDD中的一致性
```
item:<name>
```
—— 专门检查单个物品在所有GDD中的一致性

加载注册表：

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

如果文件不存在或无条目：

"实体注册表为空。请运行
/design-system
来编写GDD——注册表会在每个GDD完成后自动填充。暂无内容可检查。"

停止并退出。

从注册表构建四个查找表：

entity_map：

{ 名称 → { source, attributes, referenced_by } }

item_map：

{ 名称 → { source, value_gold, weight, ... } }

formula_map：

{ 名称 → { source, variables, output_range } }

constant_map：
```
{ 名称 → { source, value, unit } }
```

统计已注册条目总数并报告：

注册表已加载：[N]个实体，[N]个物品，[N]个公式，[N]个常量
检查范围：[full | since-last-review | entity:name]

Phase 2: Locate In-Scope GDDs

阶段2：定位待检查的GDD

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:

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.

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

排除：

game-concept.md

、

systems-index.md

、

game-pillars.md

——这些不属于系统GDD。

对于

since-last-review

模式：

bash

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

仅包含自最新的

design/gdd/gdd-cross-review-*.md

文件创建日期后修改过的GDD。

扫描前报告待检查的GDD列表。

Phase 3: Grep-First Conflict Scan

阶段3：优先Grep的冲突扫描

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

针对每个已注册条目，在所有待检查的GDD中grep该条目的名称。不要读取完整文档——仅提取匹配行及其紧邻上下文（-C 3行）。

这是核心优化点：无需读取10个GDD × 400行（共4000行），只需对50个实体名称 × 10个GDD进行grep搜索（50次定向搜索，每次命中返回约10行）。

3a: Entity Scan

3a：实体扫描

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)

针对entity_map中的每个实体：

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

针对每个GDD命中结果，提取实体名称附近提及的属性值：

任何数值属性（数量、成本、持续时间、范围、速率）
任何分类属性（类型、等级、类别）
任何衍生值（总计、输出、结果）
entity_map中注册的其他任何属性

将提取的值与注册表条目进行比对。

冲突检测规则：

注册表显示

[entity_name].[attribute] = [value_A]

，而GDD显示

[entity_name]具有[value_B]

→ 冲突

注册表显示

[item_name].[attribute] = [value_A]

，而GDD显示

[item_name]为[value_B]

→ 冲突

GDD提及
```
[entity_name]
```
但未指定属性 → 备注（无冲突，仅无法验证）

3b: Item Scan

3b：物品扫描

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.

针对item_map中的每个物品，在所有GDD中grep物品名称。提取：

售价/价值/金币价值
重量
堆叠规则（可堆叠/不可堆叠）
类别

与注册表条目值进行比对。

3c: Formula Scan

3c：公式扫描

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

针对formula_map中的每个公式，在所有GDD中grep公式名称。提取：

公式附近提及的变量名称
提及的输出范围或上限值

与注册表条目进行比对：

变量名称不同 → 冲突
输出范围表述不同 → 冲突

3d: Constant Scan

3d：常量扫描

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

针对constant_map中的每个常量，在所有GDD中grep常量名称。提取：

常量名称附近提及的任何数值

与注册表值进行比对：

数值不同 → 冲突

Phase 4: Deep Investigation (Conflicts Only)

阶段4：深度调查（仅针对冲突）

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:

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

针对阶段3中发现的每个冲突，对存在冲突的GDD进行定向的完整章节读取，以获取精确上下文：

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

（如果文件较大，也可使用更广上下文的Grep）

结合完整上下文确认冲突。确定：

哪个GDD是正确的？ 检查注册表中的
```
source:
```
字段——来源GDD是权威所有者。任何与之矛盾的其他GDD都需要更新。
注册表本身是否过时？ 如果来源GDD在注册表条目编写后已更新（查看git日志），则注册表可能已过期。
这是否是有意的设计变更？ 如果冲突代表有意的设计决策，解决方案是：更新来源GDD，更新注册表，然后修复所有其他GDD。

针对每个冲突进行分类：

🔴 冲突 —— 同一名称的实体/物品/公式/常量在不同GDD中具有不同值。必须在架构开始前解决。
⚠️ 注册表过期 —— 来源GDD的值已更改，但注册表未更新。需要更新注册表；其他GDD可能已经正确。
ℹ️ 无法验证 —— 提及实体但未说明可比对的属性。无冲突，仅记录引用。

Phase 5: Output Report

阶段5：输出报告

undefined

undefined

Consistency Check Report

一致性检查报告

Date: [date] Registry entries checked: [N entities, N items, N formulas, N constants] GDDs scanned: [N] ([list names])

日期：[date] 已检查的注册表条目：[N]个实体，[N]个物品，[N]个公式，[N]个常量已扫描的GDD：[N]个（[名称列表]）

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]

🔴 [实体/物品/公式/常量名称] 注册表（来源：[gdd]）：[attribute] = [value] 在[other_gdd].md中发现冲突：[attribute] = [different_value] → 需要解决：[需修改的文档及修改目标]

Stale Registry Entries (registry behind the GDD)

过期的注册表条目（注册表落后于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.

⚠️ [条目名称] 注册表显示：[value]（编写于[date]）来源GDD当前显示：[new value] → 更新注册表条目以匹配来源GDD，然后检查referenced_by文档。

Unverifiable References (no conflict, informational)

无法验证的引用（无冲突，仅信息）

ℹ️ [gdd].md mentions [entity_name] but states no comparable attributes. No conflict detected. No action required.

ℹ️ [gdd].md提及[entity_name]但未说明可比对的属性。未检测到冲突。无需操作。

Clean Entries (no issues found)

无问题条目

✅ [N] registry entries verified across all GDDs with no conflicts.

Verdict: PASS | CONFLICTS FOUND


**Verdict:**
- **PASS** — no conflicts. Registry and GDDs agree on all checked values.
- **CONFLICTS FOUND** — one or more conflicts detected. List resolution steps.

---

✅ [N]个注册表条目已在所有GDD中验证，无冲突。

Verdict：通过 | 发现冲突


**Verdict：**
- **通过** —— 无冲突。注册表与GDD在所有检查值上一致。
- **发现冲突** —— 检测到一个或多个冲突。列出解决步骤。

---

Phase 6: Registry Corrections

阶段6：注册表修正

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.

如果发现过期的注册表条目，询问：

"是否允许我更新
design/registry/entities.yaml
以修复[N]个过期条目？"

针对每个过期条目：

更新
```
value
```
/属性字段
将
```
revised:
```
设置为当前日期
添加YAML注释记录旧值：
```
# was: [old_value] before [date]
```

如果在GDD中发现未注册的新条目，询问：

"在GDD中发现[N]个未在注册表中注册的实体/物品。是否允许我将它们添加到
design/registry/entities.yaml
？"

仅添加在多个GDD中出现的条目（真正的跨系统事实）。

切勿删除注册表条目。 如果条目已从所有GDD中移除，设置

status: deprecated

。

完成编写后：Verdict：完成 —— 一致性检查结束。如果仍有冲突未解决：Verdict：阻塞 —— [N]个冲突需要手动解决后才能开始架构工作。

6b: Append to Reflexion Log

6b：追加到反思日志

If any 🔴 CONFLICT entries were found (regardless of whether they were resolved), append an entry to

docs/consistency-failures.md

for each conflict:

markdown

undefined

如果发现任何🔴冲突条目（无论是否已解决），为每个冲突追加条目到

docs/consistency-failures.md

：

markdown

undefined

[YYYY-MM-DD] — /consistency-check — 🔴 CONFLICT

[YYYY-MM-DD] — /consistency-check — 🔴 冲突

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.

---

领域：[涉及的系统领域] 涉及文档：[来源GDD] vs [冲突GDD] 问题描述：[具体冲突——实体名称、属性、不同值] 解决方案：[修复方式，或"未解决——需手动操作"] 经验总结：[通用教训，例如"战斗GDD中定义的物品价值在经济GDD编写前未参考entities.yaml——务必先检查entities.yaml"]


仅当`docs/consistency-failures.md`存在时才追加。如果文件缺失，静默跳过此步骤——不要通过此技能创建该文件。

---

Next Steps

后续步骤

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.

如果通过：运行
```
/review-all-gdds
```
进行整体设计理论审查，或在所有MVP GDD完成后运行
```
/create-architecture
```
。
如果发现冲突：修复标记的GDD，然后重新运行
```
/consistency-check
```
确认问题已解决。
如果注册表过期：更新注册表（阶段6），然后重新运行以验证。
编写完每个新GDD后运行
```
/consistency-check
```
，尽早发现问题，避免在架构阶段才暴露。