consistency-check

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

一致性检查

通过将所有 GDD 与实体注册表（design/registry/entities.yaml）进行比较，检测跨文档不一致。采用先 grep 的方法：读取一次注册表，然后只定位提及已注册名称的 GDD 章节；除非需要调查冲突，否则不读取完整文档。

此技能是写入时的安全网。 它能发现 /design-system 的分节检查可能遗漏的问题，以及 /review-all-gdds 的整体审查发现得太晚的问题。

运行时机：

• 编写每个新 GDD 后（开始下一个系统之前）
• /review-all-gdds 之前（让该技能从干净的基线开始）
• /create-architecture 之前（不一致会污染下游 ADR）
• 按需运行：使用 /consistency-check entity:[name] 检查指定实体

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

---

每次 AskUserQuestion 调用都遵循 .claude/docs/automation-modes.md （协作模式始终询问 · 引导模式仅在重大事项上询问 · 自主模式记录后继续； automation_always_ask 类别始终提示）。

workflow（参见 .claude/docs/workflow-modes.md），按每个 GDD 的 有效级别应用——如果 system_overrides 块中列出了该 GDD 所属系统（其 文件名主干），则采用该行的设置；否则采用项目级设置：

• full — 对照所有 GDD 章节，完整交叉检查实体注册表。
• standard — 仅对照必需章节进行交叉检查。报告的 Scope 行会说明这一点；在此级别下，Phase 3 会将必需章节之外所有已注册名称对应的值列为未检查。
• minimal — 不适用（没有可检查的 GDD）。

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

模式：

• 无参数 / full — 对照所有 GDD 检查所有已注册条目
• since-last-review — 仅检查自上次审查报告后修改的 GDD
• entity:<name> — 在所有 GDD 中检查指定实体
• item:<name> — 在所有 GDD 中检查指定物品

加载注册表：

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

如果文件不存在或没有条目：

“实体注册表为空。运行 /design-system 编写 GDD——每个 GDD 完成后都会自动填充注册表。当前没有可检查的内容。”

判定：未评估 — 实体注册表为空。停止：没有进行任何比较，因此不能给出 PASS，也没有内容可写入。

根据注册表构建四个查找表：

• 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 } }

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

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

对于 entity:<name> 或 item:<name>，如果注册表中没有该名称对应的条目，判定为 未评估 — 注册表中没有 <name>：列出最接近的已注册名称，然后停止。检查未注册名称不会比较任何内容，因此不算 PASS。

---

Phase 2：定位范围内的 GDD

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

排除位于 design/gdd/ 中但并非系统 GDD 的文档： game-concept.md、systems-index.md、game-pillars.md、gameplay-tags.md、 entity-registry.md、fixture-swap-ledger.md、sound-bible.md，以及任何 gdd-cross-review-*.md（/review-all-gdds 在此处写入报告）。

对于 since-last-review 模式：

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

仅限修改日期晚于最近创建的 design/gdd/gdd-cross-review-*.md 文件的 GDD。

扫描前报告范围内的 GDD 列表。如果列表为空——不存在系统 GDD，或 since-last-review 未发现任何改动——判定为 未评估 — 范围内没有 GDD：说明哪个筛选条件导致结果为空，然后停止。 扫描空列表不会发现冲突，因此不算 PASS。

---

阶段 3：优先使用 Grep 扫描冲突

对于每个已登记条目，在所有范围内的 GDD 中搜索该条目的名称。 不要完整读取文件——只提取匹配行及其紧邻上下文（前后各 3 行）。

这是核心优化：与其读取 10 个 GDD、每个 400 行（共 4,000 行）， 不如在 10 个 GDD 中搜索 50 个实体名称（进行 50 次定向搜索， 每次命中时约返回 10 行）。

在有效层级为 standard 的 GDD 中，仅比较必需章节下的命中项。 有效层级按 GDD 划分：system_overrides.<stem> 会在该 GDD 中以任一方向覆盖项目层级（full 条目会使每个章节都纳入比较）。对每个此类 GDD，只需用 ^## 搜索一次，以获取其标题和行号，并将每个名称命中项归入其上方最近的标题：仅比较 Overview、Detailed Rules / Detailed Design、Formulas、Edge Cases、Dependencies 或 Acceptance Criteria 下的命中项；如果 project.yaml 将 workflow_overrides.tuning_knobs 设为 true，还包括 Tuning Knobs（读取一次该标志即可；它只会增加此章节）。任何其他命中项（未启用标志时的 Tuning Knobs、Player Fantasy 或任何其他章节）都不产生发现，也不记录；在报告的 Not checked at this tier 行中，列出每个说明了数值的命中项（名称、GDD、章节）。

3a：实体扫描

对于 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] has [value_B]。→ CONFLICT
• 登记表写明 [item_name].[attribute] = [value_A]，GDD 写明 [item_name] is [value_B]。→ CONFLICT
• GDD 提及 [entity_name]，但未指定该属性。→ NOTE（无冲突，仅无法核实）

3b：物品扫描

对于 item_map 中的每个物品，在所有 GDD 中搜索该物品名称。提取：

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

将提取的值与登记条目进行比较。

3c：公式扫描

对于 formula_map 中的每个公式，在所有 GDD 中搜索该公式名称。提取：

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

与登记条目进行比较：

• 变量名称不同 → CONFLICT
• 输出范围表述不同 → CONFLICT

3d：常量扫描

对于 constant_map 中的每个常量，在所有 GDD 中搜索该常量名称。提取：

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

与登记值进行比较：

• 数值不同 → CONFLICT

---

阶段 4：深入调查（仅限冲突）

对于阶段 3 中发现的每项冲突，针对冲突的 GDD，对相关章节进行一次完整阅读，以获取准确背景：

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

（如果文件较大，也可以使用 Grep 扩大上下文范围）

按章节阅读：使用 Grep 工具查找冲突章节的标题（模式 ^#，内容模式），然后使用 offset 和 limit 读取该范围。

结合完整背景确认冲突。判断：

1. 哪个 GDD 正确？ 检查注册表中的 source: 字段——源 GDD 是权威的归属文件。任何与之矛盾的其他 GDD 都需要更新。
2. 注册表本身是否过期？ 如果源 GDD 在注册表条目写入后更新过（检查 git log），注册表可能已经过时。
3. 这是否是真正的设计变更？ 如果冲突体现的是有意作出的设计决策，解决方式是：更新源 GDD、更新注册表，然后修正所有其他 GDD。

对于每项冲突，分类如下：

• 🔴 冲突——不同 GDD 中，同一具名实体／条目／公式／常量的值不同。必须在架构工作开始前解决。
• ⚠️ 注册表过期——源 GDD 的值已更改，但注册表未更新。需要更新注册表；其他 GDD 可能已经正确。
• ℹ️ 无法核实——提到了实体，但未提供可比较的属性。这不构成冲突；仅记录该引用。

---

阶段 5：输出报告

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

结论：

• 发现冲突——检测到一项或多项冲突。列出解决步骤。
• 未评估——未进行任何比较：实体注册表为空，或其中没有该具名实体（阶段 1），或阶段 2 中没有适用范围内的 GDD。说明具体原因。
• 通过——没有冲突。至少有一个 GDD；注册表与 GDD 在所有已检查的值上均一致。

---

阶段 6：更正注册表

写入前重新阅读。 阶段 1 在扫描前读取了注册表，其他技能或会话可能已在此期间对其进行修改。每次 Edit 前，先读取当前的 design/registry/entities.yaml，在所属章节中找到相应条目，并以条目当前文本为 Edit 的锚点，切勿依据阶段 1 看到的内容。新增条目应追加到所属章节最后一个现有条目之后。

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

“我可以更新 design/registry/entities.yaml 来修正 [N] 个过期条目吗？”

对于每个过期条目：

• 更新 value／属性字段
• 将 revised: 设为今天的日期
• 添加一条 YAML 注释，注明旧值：# was: [old_value] before [date]

如果在 GDD 中发现注册表尚未收录的新条目，请询问：

“在 GDD 中发现了 [N] 个尚未收录到注册表中的实体／条目。 我可以将它们添加到 design/registry/entities.yaml 吗？”

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

绝不删除注册表条目。 如果某条目已从所有 GDD 中移除，请将其设为 status: deprecated。

写入后，运行 bash .claude/scripts/registry.sh validate，并在给出结论前修复与本次写入新增或更改的条目有关的所有行（DUPLICATE、STATUS 或 LAYOUT 行，或涉及本次命名路径的 PATH_MISSING 行）；其他条目相关的行应告知用户，不要未经询问就修复。如果脚本缺失或未输出任何内容，请说明注册表检查未运行，然后根据文件头部的规则重新检查所写条目。

写入后：结论：已完成——一致性检查已结束。 如果仍有未解决的冲突：结论：受阻——有 [N] 项冲突需要在架构工作开始前手动解决。

6b：追加到反思日志

如果发现任何 🔴 CONFLICT 条目（无论是否已解决），请询问：“我可以将 [N] 条记录追加到 docs/consistency-failures.md（如果文件不存在则创建）吗？”如果用户同意，为每个冲突追加一条记录；如果用户不同意，则说明这些冲突未记录。

### [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"]

如果 docs/consistency-failures.md 不存在，请先使用以下标题创建该文件，再追加内容：

# Consistency Failure Log




| Date | GDD A | GDD B | Conflict Type | Status |
|------|-------|-------|---------------|--------|

然后追加新的冲突记录。切勿自行跳过记录；文件不存在不是丢失冲突历史的理由，只有用户回答“否”才可以不记录。

---

第 7 阶段：会话状态与结束

静默追加到 production/session-state/active.md（如果文件不存在则创建）：

**指向 docs/consistency-failures.md——第 6 阶段实际追加内容的文件。**线索是留给未来会话跟进的指针。如果线索指向一个无人写入的文件，就会让后续会话去查找永远找不到的冲突历史，而且过程中不会报错。此处切勿虚构报告文件名。

然后使用 AskUserQuestion 小组件结束：

• 提示：“一致性检查已完成——发现 [N] 个冲突。接下来怎么做？”
• 选项：
  • [A] 立即修复优先级最高的冲突
  • [B] 对冲突最多的 GDD 运行 /design-review
  • [C] 到此为止

在协作模式和引导模式下，技能结束时绝不能只输出纯文本——始终使用此小组件结束。在自主模式下，打印检查结果和建议的下一步，然后通过 log_decision 记录（不使用小组件）。

---

恢复 / 参考

• 如果通过：运行 /review-all-gdds 进行全面的设计理论审查；如果所有 MVP GDD 均已完成，则运行 /create-architecture。
• 如果发现冲突：修复标记的 GDD，然后重新运行 /consistency-check 以确认问题已解决。
• 如果注册表过时：更新注册表（第 6 阶段），然后重新运行以验证。
• 每编写一份新的 GDD 后都运行 /consistency-check，及早发现问题，而不是等到架构阶段。