update-docs

用途

update-docs 用于研究当前代码状态，然后更新对应文档，确保文档与代码保持同步。

触发方式

关键词触发：update docs、sync docs、docs out of date、update-docs。

自动触发：在 precommit 通过后自动触发，仅当变更映射到 docs/features/ 下的功能时（参见 @rules/auto-loop.md § Tiers, gate sequence）。也可手动调用。

不适用场景

• 文档审查：使用 /codex-review-doc
• 创建新文档：使用 /tech-spec 或 /create-request
• 文档重构：使用 /doc-refactor

主要流程

第 1 步：定位文档与相关代码（五级级联）

关键原则：找不到目标时输出 ## Gate: ⚠️ Need Human，不要猜测或创建新文档。

使用共享的功能上下文解析算法（参见 @skills/create-request/references/feature-context-resolution.md）。

关于 scan_error 门控：scan_error !== false 表示源集合未知而非为空，应报告并走 ⚠️ Need Human 退出，而不是对一个无法枚举的语料库进行同步。门控条件是 !== false，而不是 === true：来自 shell 回退的 {} 载荷根本不携带该字段，而非空键并不能证明集合完整。

置信度与动作：

置信度	动作
high/medium	按检测到的功能继续
low	带警告继续
null（未找到）	输出 ## Gate: ⚠️ Need Human，不要猜测

第 1.5 步：对每个目标分类——同步权威、冻结记录

本技能重写当前权威文档，不重写记录。

scripts/lib/doc-metadata.js 中的 resolveDocRole(path, source, taxonomy) 判断文件属于哪种角色，owesCodeAlignment(path, source, taxonomy) 以布尔值给出同一答案——当文档角色为回退（当前权威）角色时，该文档才需要与代码对齐。

两个函数都以仓库路径作为第一个参数，绝不接受角色标签。

四种角色如下（来自该文件中的 BUILTIN_ROLE_CONFIG.closed_set）：

角色	匹配（path_defaults）	本技能的动作
当前权威——需要与代码对齐	4-implementation*；首段为 skills/rules/agents/commands 的任何内容；以及回退项（README.md 即通过回退解析）	重写代码变更所涉及的章节
设计记录——陈述决策	惯例上为 0-feasibility-study*、1-requirements*、2-tech-spec*、3-architecture*——但模式是 ^[0-3]-(feasibility	requirements
工作记录——陈述被要求做什么	requests/ 段下的任何内容	不重写——本技能完全不碰。/create-request --update 只能覆盖恰好四个字段（Status、Progress 表、AC 复选框、Progress.Note）；工单中其余内容冻结，已关闭工单完全冻结。这是普通更新的全部可变集合。唯一例外是已报告的事实更正——非生命周期记录的既成事实（如路径或日期），或从未作为工单陈述的未填模板占位符——也可适用于已关闭工单，仅授权该更正，绝不涉及无关的删减或清理；必须在 Progress.Note 中说明。它绝不能更改 Status、Progress 阶段状态或 AC 复选框状态：这些生命周期字段仍受冻结和普通转换规则约束
历史记录	review-log-、adr-	不重写。仅追加

owesCodeAlignment(path, source, taxonomy) 等价于 resolveDocRole(path, source, taxonomy) === FALLBACK_ROLE——仅当前权威角色，因此三个记录行是一个决策，而非三个。按角色命名，而非按位置命名。

四个规范配对——0-feasibility-study、1-requirements、2-tech-spec、3-architecture——是命名惯例（@rules/docs-numbering.md），而非分类器测试的内容。实测 2026-08-21：1-tech-spec.md、3-requirements.md、0-architecture.md 和 2-feasibility-study.md 都解析为设计记录，因为前缀和词干是独立匹配的。分类器比惯例更宽，这是有意为之，因此编号错误的规范仍受保护免于重写。停止之处在于前缀：4-tech-spec.md 越过 [0-3] 落入回退，解析为当前权威，即可重写。编号超出范围的规范会失去其名称所暗示的保护，因此应修正编号而非依赖词干。

与今日代码不一致的记录并非过时——这种不一致正是记录本身。编辑它使其一致会销毁所决定内容的唯一副本，且毫无收益：审查者按记录差异配置文件阅读记录，该配置文件不承担代码对齐义务（skills/doc-review/SKILL.md § Review Profiles）。

对被指向的记录应报告而非静默跳过——“不在重写范围内”是调用者需要的事实，沉默会被读作“已同步”。

第 2 步：研究当前代码状态

关键研究项：

• 是否新增了脚本 / 技能 / 命令？
• 现有文件是否有逻辑修改？
• 是否新增了配置或规则？
• 是否有 API 或接口变更？

第 3 步：对比文档与代码差异

项目	文档描述	当前代码	状态

第 4 步：更新文档

根据差异更新文档内容：

• 架构图（Mermaid sequenceDiagram / flowchart）
• 核心服务表
• API 描述
• 数据模型

第 5 步：验证

更新后：

• 重新阅读已更新的文档章节
• 验证所有新增模块均已记录
• 验证所有已移除模块均已清理

安全阀

文档同步后，将代码差异与同步前基线对比。如果存在新的代码变更（例如 lint:fix 修改了代码），返回审查循环。

输出

Doc Update Report

Document	Sections Updated	Status

Changes Made

• <summary of each update>

Verification

• [ ] New modules documented
• [ ] Removed modules cleaned
• [ ] Diagrams updated