audit-docs

文档审计

先读后审的审计，旨在回答“文档是否仍与实际情况一致？”。生成问题报告；不会悄悄改写文档。

回合约定——结束回合前核实

✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
✓ No doc was rewritten without explicit --fix / user go-ahead
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

准备结束回合，但还有任何一个方框未勾选？回合就尚未完成——先完成缺失的项目（弱模型会漏掉文档末尾的任务；因此将此列表放在最前面）。

适用场景

• 发布或里程碑之前、合并多个功能或修复之后，或任何文档集可能已与代码和问题记录脱节时。

步骤 0 — 发现项目（始终首先执行）

根据 Agent 指南中的 工作流约定 和 文档地图，然后阅读此技能所需的内容：路线图、修复索引及模板，以及功能文件夹布局——地图会告诉你要检查哪些链接和不变量。

检查项

运行以下检查并收集发现（每项都引用路径/行号/议题编号）：

1. 路线图 ↔ 功能目录。 每个 docs/features/<NN>-<slug>/ 都在路线图中，且路线图中的每个条目都有对应目录（或明确标记为“已排期”）。
2. 功能依赖。 SPEC 中的 Depends on / Branch 字段有效；没有依赖循环；顺序与路线图一致。
3. 修复索引卫生。 每个条目都对应一个开放议题和一个尚未合并的分支；标记议题已关闭或 PR 已合并的条目（这些条目本应已移除）。标记索引中遗漏的开放修复分支。
4. 文档映射链接可解析。 映射中引用的每个文件都存在；标记“已排期，尚未编写”的条目，以免误认为是偏差。
5. 文档内链接失效。 相对链接/锚点均指向真实文件/章节。
6. 议题引用。 验收/已知问题行中引用 #N 的内容，没有在未注明的情况下指向已长期关闭的议题。
7. 语言与命名规范。 文档采用项目要求的语言（本仓库：英语）；文件/目录命名符合规范（例如，TypeScript 文件使用 kebab-case，组件使用 PascalCase）。
8. 不变量标签。 如果项目使用不变量/决策 ID（例如 INV-/D-/KI-），抽查所引用的 ID 是否确实存在且符合说明。
9. done 行的 PR 链接完整性。 每个状态为 done 的路线图行（以及修复索引条目）都带有已链接的 PR 引用—— done · [#<pr>](<pr-url>)。对于每个裸写的 done，在代码托管平台上查找其 PR（运行 gh pr list --state all --head feat/<NN>-<slug> 或按标题搜索），并提出行更新建议；如果完全找不到 PR，则该 done 属于高严重性问题（该单元可能从未完成收尾）。

工作流规范（检查 10–14）——执行器技能会在写入时强制执行这些要求；本审计将核实它们是否确实得到遵守。每项检查均为机械检查：运行所示命令，不要推断。

10. 阶段命名。 grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md 必须无结果——计划只能使用阶段（phases）P1, P2, …。任何命中项：低严重性（重命名），并检查执行器参数是否仍能解析。
11. 每阶段文档规范。 对每个状态为 in-progress/done 的 M/L 功能：已完成阶段须在 TASKS.md 中勾选，progress.md 中每个已完成阶段须有一条记录，并且（依据当前模板规划的功能）最后一个阶段须以以下收尾任务原文结尾：创建 PR 并打印 URL、关联路线图行、推送链接提交。done 功能存在未勾选任务，或某个阶段未出现在 progress.md 中：高严重性。
12. 与代码托管平台核对分支和 PR 规范。 对每个已完成单元：其 PR 存在、目标分支为默认分支、描述非空；如果该单元由议题发起（SPEC 引用了议题），则 PR 中包含 Closes #<n>。还要扫描默认分支近期历史（git log --first-parent），检查是否有直接提交的、属于某个功能/修复的更改：高严重性。
13. 生成文档来源追溯（仅当文档映射中声明了 Docs site 区块时；否则说明不适用）。 扫描声明的内容目录，查找孤立页面。 每个页面：(a) 其 source-unit 存在于路线图或修复索引中——若无匹配项，则为孤立页面（低严重性：建议删除或重新归属）；(b) 该单元的 PR 合并时间晚于页面的 updated 日期，且提交更改了与该页面主题相关的路径——则该页面为过时页面（低严重性：提出建议）。每项发现均引用页面路径和单元。
14. 提交格式与依赖规范。 抽查各单元分支的提交：符合 <type>(<scope>): <summary> 规范格式（违规项：低严重性）。每个 in-progress/done 行的 Depends on: 依赖闭包均已合并——基于未合并依赖构建的单元属于高严重性问题，除非 decisions.md 记录了用户强制覆盖（--force），这种情况降为低严重性（已记录的风险）。

根据项目实际结构调整检查清单；跳过不存在的结构，并说明原因。

流程

1. 先发现，再使用 grep、读取文件和 forge CLI 执行检查 （遵循 Workflow conventions；示例使用 gh）。

2. 生成调查结果报告——必须原样返回（固定输出约定）：

   AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>
   
   | # | Check (1-14) | Finding | Sev | Evidence | Proposed fix |
   |---|-------------|---------|-----|----------|--------------|
   | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
   
   Checks run: <n>/14 (skipped: <which + why — absent structures only>)
   Summary: <1-2 sentences>
   Decision: PASS | FAIL   (FAIL if any high-severity finding is open)
   

   Sev：high = 有误导性或已损坏；low = 外观问题。 此图例仅定义了 high 和 low

3. 仅在收到请求时修复。 只有明确指定 --fix（或用户同意）后，才应用低风险修正（移除已合并的 fix-index 行、修复失效链接、登记缺失的路线图条目、为只有 done 的行添加已核实的 PR 链接）。判断性问题留给用户决定。

防护措施

• 先阅读；未经提示，绝不批量改写文档。
• 区分实际偏差与有意的“已排期／已延期”事项—— 不要将有意的权衡报告为错误。
• 仅在文档范围内进行精简修改；不修改代码或行为。

可移植性（Claude Code 以外的 Agent）

工作流才是约定；Claude Code 功能只是便利工具。若 Agent 不具备某项功能，请采用回退方案——绝不跳过该功能所支持的步骤：

• 没有斜杠命令菜单——若此技能要求使用 /<skill>，请打开该技能的 SKILL.md（无论技能安装在 Agent 的何处），并在新的对话中逐字遵循：交接默认使用干净的上下文。
• 没有按技能设置的 model:/effort:——没有技能固定模型层级；请自行选择：这些工作大多是机械式的跨文档检查；中等层级模型就足够，只有深入审计时才升级到最强模型。

与其他技能的关系

• 与 unit-lane（创建本技能审计的文档）和 triage-issue（确保修复索引准确）互为补充。
• 可随时独立运行；无需先运行其他技能。

完成条件

• 已生成按严重程度排序的调查结果报告，并已应用所有获批准的低风险修正——真正的延期事项保持不变，并标注为延期。

• 已打印结尾的 → Next: 区块：

  → Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
    · real drift (not cosmetic) → /triage-issue   · a concrete defect → /unit-lane --fix <n>
    · already clean → nothing to do