content-audit

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

自动化模式：解析 modes.automation（project.local.yaml → project.yaml → 默认值 collaborative）。每次调用 AskUserQuestion 和 每次文件写入都遵循 .claude/docs/automation-modes.md （collaborative 始终询问 · guided 仅询问重大事项 · autonomous 记录并继续； automation_always_ask 类别始终询问）。

已在上方解析 — 按原样使用。没有代码块 → 使用 .claude/docs/config-resolution.md 中的默认值。

内容审计

审计前先解析 modes.workflow：此技能依赖层级的行为 （“仅审计必需章节中的规格”）遵循已解析的层级，不得假定层级。 当必需输入（例如 design/gdd/systems-index.md）缺失时，应报告 NOT ASSESSED — NO DATA，而不是计算差距百分比（没有任何规格时会 导致除以零）。

调用此技能时：

解析参数：

• 无参数 → 审计所有系统
• [system-name] → 仅审计该系统
• --summary → 仅输出汇总表，不写入文件

---

workflow（参见 .claude/docs/workflow-modes.md）：

• full — 对照所有 GDD 规格进行完整的内容数量审计。
• standard — 仅审计必需章节中的规格；将其中发现的任何其他数量列为此层级未审计。
• minimal — 无法运行（不存在系统索引）。

输入不足 — 生成任何报告前先检查

如果此技能所需的输入不存在，答案就是“无法运行”—— 而不是一份填好的报告。 先检查，检查未通过就停止。

1. 列出此技能读取的输入（数据文件、先前报告、分析器输出、 测试结果、注册表、源代码）。
2. 对每一项，记录 FOUND 或 ABSENT——不要“假定存在”。
3. 如果某个章节所需的任何输入为 ABSENT，该章节应标记为 NOT ASSESSED — NO DATA。不要估算，不要从相邻产物推断，也不要把模板中 必须填写的单元格留给后续阅读者填写。
4. 如果所有必需输入均为 ABSENT，则停止并将 NOT ASSESSED — NO DATA 作为整体结论报告，指出缺少的内容以及生成这些内容的技能（/map-systems 用于 design/gdd/systems-index.md，/design-system 用于 GDD）。

结论为 NOT ASSESSED 是成功的。 当没有数据时，这是对 “数据说明了什么？”这一问题正确且有用的答案。此举旨在防止一种特定的失败： 结论枚举中没有“无法运行”状态的报告会造成 虚假的通过结果——例如，在没有资产且没有标准的项目中，资产审计却返回 COMPLIANT；或者在没有分析器数据且从未设置预算时，性能分析却报告“相对于 16.67ms 预算还有 >99% 余量”。

没有证据绝不等于证明不存在。 如果没有文件可扫描，扫描自然找不到匹配项，这并不能验证任何内容。要说明究竟发生了哪种情况——仅凭绿色结果，读者无法判断。

阶段 1 — 收集上下文

1. 阅读 design/gdd/systems-index.md，了解系统的完整列表、分类以及 MVP/优先级层级。按章节阅读：使用 Grep 工具（模式 ^#，内容模式）查找所需标题，再用 offset 和 limit 读取对应范围。

2. 优先统计注册表：如果 design/registry/entities.yaml 存在，先读取它。其中的 entities 和 items 部分是本次审计统计的跨 GDD 命名内容，每个条目都已提炼出一个 source: GDD：

   Grep pattern="^  - name:" path="design/registry/entities.yaml" output_mode="content" -A 2
   

   - name: 会出现在注册表的四个部分中；只保留 -A 2 上下文显示它们位于 entities: 或 items: 下的名称（这是本次审计统计的命名内容，不包括 formulas:/constants:）。将这些名称作为计划中的命名内容集，无需完整读取其所属的 GDD。 如果 design/registry/entities.yaml 不存在或没有条目（在 /design-system 填充之前，它会是一个空存根），跳过此步骤并依赖下方的 GDD 扫描——行为不变，只是成本更高。

3. L0 预扫描：在完整读取任何 GDD 之前，运行两次 grep——它们回答不同的问题，不得共用同一模式：

   a. 哪些 GDD 包含 Summary（分母／开放处理检查）：

   Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="files_with_matches"
   

   b. 哪些 GDD 实际声明了内容数量（缩小范围的步骤）：

   Grep pattern="[0-9]+[[:space:]]+(enemies|enemy types|levels|areas|maps|stages|items|weapons|equipment|abilities|skills|spells|cutscenes|conversations|dialogue scenes|bosses|quests)|(enemy|item|weapon|ability|level) types:" glob="design/gdd/*.md" output_mode="files_with_matches"
   

   两次扫描要分开进行。 ## Summary 会匹配所有符合规范的 GDD，因此与它取并集不会缩小范围；像 N enemies 这样的字面占位符则不会匹配任何真实 GDD。模式 (b) 会匹配数字后接第 5 步实际提取的内容名词。

   对缺失的 Summary 采用开放处理。 确定分母：对 design/gdd/*.md 执行 glob 并统计数量 N。扫描 (a) 的匹配数少于 N，表示这些 GDD 早于 ## Summary——绝不可将缺少 Summary 的 GDD 视为系统不在审计范围内；扫描 (a) 匹配数为零，表示“尚无 GDD 包含 Summary”，而不是“没有可审计内容”。完整读取未匹配且属于范围内的 GDD。

   对单系统审计：跳过此步骤，直接完整读取。 对完整审计：完整读取扫描 (b) 匹配且尚未由步骤 2 中的注册表条目完全覆盖的 GDD，以及扫描 (a) 未匹配的所有 GDD——开放处理规则优先于缩小范围：没有 ## Summary 的 GDD 即使未被扫描 (b) 匹配，也必须完整读取。只有包含 Summary 且不含内容数量相关表述的 GDD（纯机制类 GDD），才可标记为“无可审计内容数量”，而无需完整读取。

4. 完整读取范围内的 GDD 文件（如果给出了系统名称，则读取该系统对应的 GDD）。此步骤需要读取整个 GDD：按标题分段读取（使用 Grep 工具，以 ^# 为模式并启用内容模式查找标题），因为超过 40 KB 的整文件 Read 会被拒绝。

5. 针对每个 GDD，提取明确的内容数量或列表，并记录它们所属的 ## 章节——在 standard 层级，不在必需章节（.claude/docs/workflow-modes.md）内的数量要列入“此层级不审计”，绝不能纳入清单。查找以下模式：

   • “N 个敌人”／“敌人类型：”／具名敌人列表
   • “N 个关卡”／“N 个区域”／“N 张地图”／“N 个阶段”
   • “N 个物品”／“N 件武器”／“N 件装备”
   • “N 种能力”／“N 个技能”／“N 个法术”
   • “N 段对话场景”／“N 段对话”／“N 段过场动画”
   • “N 个任务”／“N 项任务”／“N 个目标”
   • 任何明确列出的内容（具名内容项的项目符号列表）

6. 根据提取的数据构建内容清单表格：

   系统	内容类型	指定数量／列表	来源 GDD

   注意：如果 GDD 仅定性描述内容而未给出数量，记录“未指定”并标记出来——未指定数量是值得注意的设计缺口。

阶段 2 — 实现扫描

对于阶段 1 中发现的每种内容类型，扫描相关目录，统计已实现的内容。使用 Glob 和 Grep 定位文件。

在 Unreal 中，内容位于 Content/ 下——包括地图和数据资产——而代码根目录（Source/<Module>/）仅包含 C++ 代码。因此，在 Unreal 中，以下每个 assets/… glob 也会在 Content/ 下运行（用 *.uasset 替代数据扩展名），关卡文件为 Content/**/*.umap。跳过此步骤会导致每个 Unreal 项目都找不到任何关卡，并将其报告为 NOT STARTED。

在 Unity 中，内容位于 Assets/ 下（大小写必须完全一致——.claude/docs/code-root-resolution.md），极少位于 data/ 文件夹中。因此，在 Unity 中，以下每个 assets/… glob 也会在 Assets/ 下运行，且不要求包含 data/ 段——对于物品，使用 Assets/**/items/**、Assets/**/Items/** 和 Assets/**/*Item*.asset；数据文件包括 .asset（ScriptableObjects）和 .prefab。跳过此步骤会导致 Unity 项目中的物品、能力、任务和对话均为零，并将其报告为 NOT STARTED。

关卡 / 区域 / 地图：

• Glob assets/**/*.tscn、assets/**/*.unity、assets/**/*.umap
• 在代码根目录中 Glob 场景文件：*.tscn（Godot）、*.unity（Unity）；在 Unreal 中改用 Content/**/*.umap（如上所述）。根据 .claude/docs/code-root-resolution.md 确定根目录。如果无法解析代码根目录，报告 NOT ASSESSED — code root unresolved，而非命中数为零。
• 查找名为 levels/、areas/、maps/、worlds/、stages/ 的子目录中的场景文件
• 统计看起来是关卡 / 场景定义的唯一文件（不包括 UI 场景）

敌人 / 角色 / NPC：

• Glob assets/data/**/enemies/**、assets/data/**/characters/**
• Glob <code root>/**/enemies/**、<code root>/**/characters/**
• 查找定义实体属性的 .json、.tres、.asset、.yaml 数据文件
• 查找角色子目录中的场景 / 预制件文件

物品 / 装备 / 战利品：

• Glob assets/data/**/items/**、assets/data/**/equipment/**、assets/data/**/loot/**
• 查找 .json、.tres、.asset 数据文件

能力 / 技能 / 法术：

• Glob assets/data/**/abilities/**、assets/data/**/skills/**、assets/data/**/spells/**
• 查找 .json、.tres、.asset 数据文件

对话 / 会话 / 过场动画：

• Glob assets/**/*.dialogue、assets/**/*.csv、assets/**/*.ink
• 在 assets/data/ 中 Grep 对话数据文件

任务 / 使命：

• Glob assets/data/**/quests/**、assets/data/**/missions/**
• 查找 .json、.yaml 定义文件

引擎专属说明（在报告中注明）：

• 计数均为近似值——此技能无法完美解析每种引擎格式，也无法区分仅供编辑器使用的文件和随产品发布的内容
• 场景文件可能既包括游戏内容，也包括系统 / UI 场景；扫描会统计所有匹配项，并注明这一限制

---

阶段 3 — 差距报告

生成差距表：

| System | Content Type | Specified | Found | Gap | Status |
|--------|-------------|-----------|-------|-----|--------|

状态类别：

• COMPLETE — 找到数量 ≥ 指定数量（100% 及以上）
• IN PROGRESS — 找到数量为指定数量的 50–99%
• EARLY — 找到数量为指定数量的 1–49%
• NOT STARTED — 找到数量为 0

优先级标记： 如果符合以下条件，则在报告中将系统标记为 HIGH PRIORITY：

• 状态为 NOT STARTED 或 EARLY，并且
• 系统索引将其标记为 MVP 或 Vertical Slice，或者
• 系统索引显示该系统阻塞了下游系统

摘要行：

• 指定内容项总数（Specified 列所有数值之和）
• 已找到内容项总数（Found 列所有数值之和）
• 总体差距百分比：(Specified - Found) / Specified * 100

如果某行的 Found 为 NOT ASSESSED（代码根目录无法解析），则不填写 Gap 或 Status，不得标记为 NOT STARTED，也不计入上述总数；摘要中须指出该行。

---

阶段 4 — 输出

完整审计和单系统模式

向用户展示差距表和摘要。询问：“我可以将完整报告写入 docs/content-audit-[YYYY-MM-DD].md 吗？”

如果可以，写入文件：

# Content Audit — [Date]

## Summary
- **Total specified**: [N] content items across [M] systems
- **Total found**: [N]
- **Gap**: [N] items ([X%] unimplemented)
- **Scope**: [Full audit | System: name] — [all GDD sections | required sections only (workflow: standard)]
- **Not audited at this tier**: [counts found only outside the required sections — or "none"; omit at `full`]

> Note: Counts are approximations based on file scanning.
> The audit cannot distinguish shipped content from editor/test assets.
> Manual verification is recommended for any HIGH PRIORITY gaps.

## Gap Table

| System | Content Type | Specified | Found | Gap | Status |
|--------|-------------|-----------|-------|-----|--------|

## HIGH PRIORITY Gaps

[List systems flagged HIGH PRIORITY with rationale]

## Per-System Breakdown

### [System Name]
- **GDD**: `design/gdd/[file].md`
- **Content types audited**: [list]
- **Notes**: [any caveats about scan accuracy for this system]

## Recommendation

Focus implementation effort on:
1. [Highest-gap HIGH PRIORITY system]
2. [Second system]
3. [Third system]

## Unspecified Content Counts

The following GDDs describe content without giving explicit counts.
Consider adding counts to improve auditability:
[List of GDDs and content types with "Unspecified"]

写入报告后，询问：

“你想为任何内容差距创建待办事项吗？”

如果可以：针对用户选择的每个系统，建议一个事项标题，并根据差距大小，引导用户使用 /create-stories [epic-slug] 或 /quick-design。

--summary 模式

直接在对话中打印差距表和摘要。不要写入文件。 以此结束：“运行不带 --summary 的 /content-audit 以写入完整报告。”

---

第 5 阶段 — 后续步骤

审计完成后，推荐最有价值的后续操作：

• 如果有任何系统为 NOT STARTED 且标记为 MVP → “运行 /design-system [name]，在开始实施前将缺失的内容数量添加到 GDD 中。”
• 如果总差距 >50% → “运行 /sprint-plan，将内容工作分配到接下来的冲刺中。”
• 如果有任何系统被标记为 HIGH PRIORITY → “针对每个 HIGH PRIORITY 差距运行 /create-stories [epic-slug]。”
• 如果使用了 --summary → “运行 /content-audit（不带标记）以将完整报告写入 docs/。”

根据本次运行的结果给出结论：

• 结论：COMPLETE — 内容审计已完成。
• 结论：NOT ASSESSED — NO DATA — 缺少必需的输入（见顶部的说明）、范围内没有任何内容可计数（没有注册表条目，且每个 GDD 均为 “Unspecified” 或 “No auditable content counts”），或者无法获取 Found 数量（NOT ASSESSED — code root unresolved）；请说明具体原因；对于缺失的数量，指出 /design-system。如果本次运行无法计算差距，绝不输出 COMPLETE。