技能 (Skill)：发版后同步文档

目的 (Purpose)

在代码发版或 PR 合并后，确保项目文档（README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、CHANGELOG、TODOS）与已交付变更一致，保持可发现性与跨文档一致性。

核心目标（Core Objective）

首要目标：产出与发版变更一致的文档更新；事实性修正自动完成，主观或风险性变更经用户确认。

成功标准（必须满足所有要求）：

✅ 基准分支已检测：从 CLAUDE.md、.ai-cortex/config.yaml 或 gh 推断 base branch；参见 docs/guides/project-config.md
✅ Diff 与逐文件审计：git diff、git log 已执行；README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md 已对照 diff 核对；分类为 Auto-update 或 Ask user
✅ CHANGELOG 仅润色：不重写、不删除、不替换既有条目；VERSION 变更须经 AskUserQuestion 确认
✅ 跨文档一致性：版本号、能力列表、可发现性链接已核对
✅ 变更已提交：若有修改，单次 commit 并输出 doc health summary

验收测试：新贡献者能否仅凭 README/CONTRIBUTING 正确完成首次贡献流程？

范围边界（Scope Boundaries）

本技能负责：

发版后文档事实性更新（路径、计数、能力列表、示例）
CHANGELOG 措辞润色（非重写）
TODOS.md 已完成项标记、交叉引用
跨文档一致性检查与可发现性（README/CLAUDE 链接）
文档健康状态摘要输出

本技能不负责：

建立或更新制品规范（使用 discover-docs-norms）
文档健康评估与缺口计划（使用 assess-docs）
从零引导文档结构（使用 bootstrap-docs）
提交代码变更（本技能仅更新文档并 commit）

转交点：文档同步完成后，移交给后续发版流程或下一个任务。若发现规范违规，建议运行 assess-docs。

使用场景（Use Cases）

用户要求发版后更新文档、同步文档或 post-ship docs
PR 已创建或合并，需确保文档与变更一致
CHANGELOG 措辞需润色为面向用户的语气
跨文档版本号或能力列表不一致需修复

行为（Behavior）

前置：检测基准分支

若存在 CLAUDE.md 或 .ai-cortex/config.yaml，优先读取 base_branch
否则：gh pr view --json baseRefName -q .baseRefName（若有 PR）；失败则 gh repo view --json defaultBranchRef -q .defaultBranchRef.name；均失败则 main
输出检测到的 base branch

Step 1：Pre-flight 与 Diff 分析

若当前在 base branch，中止："请在 feature branch 上运行。"
执行：git diff <base>...HEAD --stat、git log <base>..HEAD --oneline、git diff <base>...HEAD --name-only
发现文档文件：find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" | sort
将变更分类：新功能、行为变更、移除、基础设施
输出："分析 N 个文件变更、M 次提交，发现 K 个文档待审核。"

Step 2：逐文件文档审计

对 README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md 及项目内其他 .md：

README：能力/功能列表是否与 diff 一致？安装/示例是否仍正确？
ARCHITECTURE：组件与设计说明是否与代码一致？仅更新被 diff 明确否定的内容
CONTRIBUTING：新贡献者按步骤能否成功？命令是否有效？
CLAUDE.md：项目结构、命令是否准确？

每项更新分类为 Auto-update（事实性、diff 明确）或 Ask user（叙述性、大面积重写、安全模型、歧义）。

Step 3：应用 Auto-update

对明确的事实性更新直接使用 Edit 工具修改。每处修改输出一行摘要（具体改了什么）。

禁止自动更新：README 定位、ARCHITECTURE 设计理由、安全模型、删除整节。

Step 4：风险变更确认

对 Step 2 标记为 Ask user 的项，使用 AskUserQuestion，附 RECOMMENDATION 与选项（含 Skip）。用户确认后立即应用。

Step 5：CHANGELOG 措辞润色

禁止重写或替换 CHANGELOG 条目。

仅修改既有条目内措辞；不删除、不重排、不整体替换
语气：面向用户；突出「可做什么」而非实现细节
若有问题，用 AskUserQuestion，不静默修复

Step 6：跨文档一致性与可发现性

README 能力列表与 CLAUDE.md 一致？
ARCHITECTURE 与 CONTRIBUTING 结构一致？
CHANGELOG 版本与 VERSION 文件一致？
每个文档是否可从 README 或 CLAUDE 链接到达？

Step 7：TODOS.md 清理

若存在 TODOS.md：将 diff 明确完成的项移至 Completed；保守标记。可选：检查 diff 中的 TODO/FIXME 是否应进入 TODOS。

Step 8：VERSION bump 确认

禁止擅自 bump VERSION。

若 VERSION 已在本 branch 修改：检查 CHANGELOG 是否覆盖全部变更
若未修改：AskUserQuestion（A) Bump PATCH B) Bump MINOR C) Skip）
推荐 C（仅文档变更通常不需 bump）

Step 9：提交与输出

若无文档修改：输出 "All documentation is up to date." 并结束
若有修改：git add <files>、git commit -m "docs: sync documentation for release"、输出 doc health summary

Doc health summary 格式：

Documentation health:
  README.md       [Updated|Current] (description)
  ARCHITECTURE.md [Updated|Current|—] (description)
  CONTRIBUTING.md [Updated|Current|—] (description)
  CHANGELOG.md    [Voice polished|Current|—] (description)
  TODOS.md        [Updated|Current|—] (description)
  VERSION         [Not bumped|Already bumped|Skipped] (description)

输入与输出 (Input & Output)

输入

可选：base branch 名称；否则从项目配置或 gh 推断
包含未合并文档变更的 feature branch

产出

更新的文档文件（若有）及单次 commit
结构化的 doc health summary

限制（Restrictions）

硬边界

不重写、不替换、不删除 CHANGELOG 既有条目
不擅自 bump VERSION；始终用户确认
不使用 Write 覆盖 CHANGELOG；使用 Edit 精确匹配
不在 base branch 上运行

技能边界 (Skill Boundaries)

不要做这些（其他技能可以处理它们）：

建立规范：使用 discover-docs-norms
评估文档健康：使用 assess-docs
引导文档结构：使用 bootstrap-docs

自检（Self-Check）

成功标准

基准分支已正确检测
Diff 已分析并分类
逐文件审计已完成；Auto-update 已应用
CHANGELOG 仅润色，未重写
VERSION 变更经用户确认
跨文档一致性已核对
若有修改，已 commit 并输出 summary

验收测试

新贡献者能否仅凭 README/CONTRIBUTING 完成首次贡献？

示例（Examples）

示例 1：功能发版后同步

场景：新技能 sync-release-docs 已合并，需更新 README 能力表与 CHANGELOG。

步骤：检测 base branch → 分析 diff → 发现 README 缺新技能、CHANGELOG 已有条目 → Auto-update README 表 → 润色 CHANGELOG 措辞 → 确认不 bump VERSION → commit。

示例 2：无变更

场景：文档已与 diff 一致。

输出：All documentation is up to date.

附录：输出合约 (Appendix: Output Contract)

本技能产出更新后的文档与单次 commit：

元素	格式	必填字段	路径模式
文档变更	文件 diff	涉及 README / ARCHITECTURE / CONTRIBUTING / CLAUDE.md / CHANGELOG / TODOs；每项含 reason	项目根及 docs/ 下相应文件
提交	git commit	单次 commit；message 遵循 Conventional Commits；body 列出 synced 文件清单	git history
健康摘要	结构化聊天输出	字段：files_updated[]、files_skipped[]（含理由）、todos_resolved[]、commit_hash	标准输出

sync-release-docs