Doc Sync 是一个发布后文档同步技能，入口为已合并到主分支的变更，出口为文档一致性报告，完成后可进入 reflect-team-documentation（可选）或回到项目工作，前置加载 CANON.md，输出路径为 ship-workflow-ship。
用途 该技能用于在代码已合并、需要同步更新项目文档时，确保文档与代码事实保持一致。它明确不适用于：代码或产物尚未合并（文档同步会基于不稳定事实）；只是写新功能文档而非发布后修正项目真相；变更没有影响 README、架构说明、命令、路径、版本或用户文档。
核心原则 技能以“事实 vs 叙事二元性”为核心锚点，区分事实性更新和叙事性变更。事实性更新包括路径、版本号、数量、命令、配置字段、链接、拼写，直接执行不询问；叙事性变更包括新功能描述、架构理由、新增章节、迁移指南、弃用通知、项目定位，必须逐条询问 human partner。混淆两者会导致文档失去人的视角、变成谎言。
主要流程 Step 1 Diff 分析：收集合并 commit 涉及的文件（git diff-tree --no-commit-id --name-only -r <merge-sha>），并分类变更对文档的影响，例如代码文件影响 README/ARCHITECTURE/API 文档，配置文件影响部署章节，依赖文件影响安装文档，CI/CD 文件影响 CONTRIBUTING。 Step 2 逐文档审计：交叉引用变更文件与项目文档，检查 README.md 的项目描述、安装步骤、快速开始、特性列表；CLAUDE.md 的命令映射、技能列表、项目结构；AGENTS.md 的入口合同、激活门、命令映射；docs/contracts/*.md 的运行时详细规则；ARCHITECTURE.md 的组件关系、数据流、技术栈；CHANGELOG.md 的版本条目、变更类型；CONTRIBUTING.md 的开发流程、PR 规则、CI 说明。 Step 3 自动更新事实性内容：对事实性不一致直接修复，每处修改记录到文档一致性报告，不修改叙事性内容，不添加新章节，数量变更必须先验证实际数量。 Step 4 询问叙事性变更：对叙事性不一致逐条询问 human partner，每次一个问题，包含文件路径、具体位置、当前内容、变更原因，由 human partner 提供新内容或选择跳过，不替 human partner 写叙事性内容。 Step 5 CHANGELOG 润色：检查最新条目，绝不覆盖或删除历史条目，只润色最新条目措辞，保持与已有格式一致，变更类型包括 Added / Changed / Fixed / Deprecated / Removed / Security，每条以动词开头。 Step 6 跨文档一致性检查：验证版本号、特性列表、组件列表、命令列表、API 端点等同一事实在所有文档中表述一致，不一致时以代码为真实来源更新文档。 Step 7 可发现性检查：确认每个文档都能从入口点（README.md 或 CLAUDE.md）通过链接到达，孤立文档需添加引用。
验证与输出 输出或记录必须包含输入/来源、执行动作、验证结果、阻塞/回退。输出模板涵盖事实性更新、叙事性更新、CHANGELOG、一致性检查和可发现性。验证清单包括所有变更文件已识别并分类、事实性更新已自动执行并记录、叙事性变更已逐条询问、CHANGELOG 仅润色最新条目、版本号跨文档一致、特性列表跨文档一致、组件列表跨文档一致、所有文档可从入口点到达、文档一致性报告已输出。
常见说辞与红旗 技能列出常见误区，如“文档以后再更新”“CHANGELOG 自己写就行”“README 不需要那么详细”“这个文档没人看”“自动更新就行，不用问”，并给出相应现实与后果。红旗包括不区分事实与叙事全部自动修改、修改或删除 CHANGELOG 历史条目、不验证数量就更新数字、添加 human partner 不知道的新章节、跳过跨文档一致性检查、存在孤立页面、以“文档不重要”跳过流程、一次列出多个问题批量回答。
验证失败处理 针对变更文件识别不全、事实性更新未执行、叙事性变更未询问、CHANGELOG 历史被修改、跨文档数量不一致等情况，给出扩展 diff 范围、立即修正事实性更新、回滚叙事性修改并逐条询问、恢复历史条目、以代码为真实来源验证后更新所有文档等处理方式。