skill-doc-sync

宿主：Codex CLI — 此技能专为 Claude Code 设计，并已适配 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前 Codex Shell 和子 Agent 工具。在当前会话尚未提供某个提供商、模型或宿主子 Agent 前，不要声称其可用。 有关宿主工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

发布后文档同步

为交付阶段自动同步文档。代码提交并创建 PR 后，此技能会读取项目中的所有 .md 文件，对照差异，自动更新事实性内容、检查文档间的一致性，并更新 PR 正文。

限制

• 最多扫描 30 个文档文件 — 超出上限的文件将跳过，并提醒用户
• 绝不覆盖 CHANGELOG — 只追加，绝不删除现有条目
• 更改叙述或理念部分前先征求用户意见 — 有风险的更改需要确认

步骤 1：查找文档

查找项目根目录（最大深度为 2）中的所有 .md 文件，跳过 node_modules/ 和 .git/。

# Discover all markdown files (max depth 2, skip noise directories)
DOC_FILES=$(find . -maxdepth 2 -name '*.md' \
  -not -path './node_modules/*' \
  -not -path './.git/*' \
  -not -path './vendor/*' \
  -not -path './.claude/*' \
  2>/dev/null | head -30)

DOC_COUNT=$(echo "$DOC_FILES" | wc -l | tr -d ' ')
echo "Found $DOC_COUNT doc files to scan (cap: 30)"

if [[ "$DOC_COUNT" -ge 30 ]]; then
  echo "WARNING: Doc file cap reached (30). Some files may be skipped."
fi

读取每个找到的文档文件，以便掌握其当前内容。

步骤 2：对照差异

运行 git diff --stat HEAD~1（如果当前在功能分支上，则与基准分支对比），找出哪些文件发生了变化，以及每份文档中哪些内容可能已过时。

# Get the diff stat to identify changed files
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
  DIFF_STAT=$(git diff --stat HEAD~1)
  DIFF_FULL=$(git diff HEAD~1)
else
  BASE_BRANCH=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
  DIFF_STAT=$(git diff --stat "$BASE_BRANCH"..HEAD)
  DIFF_FULL=$(git diff "$BASE_BRANCH"..HEAD)
fi

echo "$DIFF_STAT"

逐一检查文档文件，确认文档中提到的路径、函数名、数量或版本号是否受到差异影响。

步骤 3：自动修正事实性内容

自动修正路径、数量、表格条目和版本号。这些是不会改变含义的机械性更改。

自动更新目标：

• 差异中重命名或移动过的文件路径
• 数字数量（例如，测试数量变化时，将“42 tests”中的数字更新）
• 版本字符串（例如，package.json 升级后更新 v9.5.0）
• 引用了重命名或删除项的表格条目
• 已变更的导入/require 路径

原因： 过时的事实性引用会削弱文档的可信度。用户看到错误的路径或数量，就会怀疑文档中的其他内容。

步骤 4：检测高风险更改

标记文档中叙述、理念或安全相关的部分，征求用户确认。不要自动编辑这些内容。

高风险类别（需要用户批准）：

• 标题包含“Philosophy”“Principles”“Vision”“Mission”“Security”“Threat Model”或“Architecture Decision”的部分
• 表达观点、策略或理由的段落（不只是陈述事实）
• ## Why 或 ## Rationale 标题下的内容
• 除版本号升级外，对 SECURITY.md 或 CONTRIBUTING.md 的任何更改

原因： 叙述和理念部分体现了人的判断。擅自改写可能会歪曲项目的意图。

检测到高风险更改时，向用户展示：

The following doc sections may need updating but contain narrative/philosophy content.
I will NOT auto-edit these. Please review and confirm each change:

1. README.md ## Philosophy — mentions "single-binary deployment" but diff adds Docker support
2. SECURITY.md ## Threat Model — new auth endpoint not documented

Approve changes? (list numbers to approve, or "skip all")

步骤 5：润色 CHANGELOG 文风

对 CHANGELOG 中的每条内容进行“推介测试”：“用户读到这条内容时，会不会想‘不错，我想试试’？”

规则：

• 先写用户收益，而非实现细节
• 使用主动语态（“添加 X”，而非“X 已添加”）
• 每条控制在 120 个字符以内
• 绝不删除现有 CHANGELOG 条目（只追加）
• 按 Added、Changed、Fixed、Removed 分组（Keep a Changelog 格式）

转换示例：

BAD:  "Refactored spawn_agent to use parameter expansion instead of basename"
GOOD: "Speed up agent spawning by eliminating 750 subshell forks (92% reduction)"

BAD:  "Added SUPPORTS_MCP_ELICITATION flag"
GOOD: "Support MCP elicitation for richer interactive prompts (CC v2.1.76+)"

原因： CHANGELOG 是面向开发者的营销文案。每条内容都应让人想要升级。

步骤 6：跨文档一致性

检查所有文档文件中的关键值是否一致。

一致性检查：

• README.md、CLAUDE.md、package.json、CHANGELOG.md 以及其他任何引用当前版本的文件中的版本号是否一致
• README 中的功能列表是否与实际实现一致（与命令／技能目录交叉核对）
• 徽章 URL 和 shield.io 引用是否为最新
• 文档之间的链接是否有效（相对路径引用）
• 命令数量和技能数量是否与实际目录列表一致

# Example: check version consistency
PKG_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": *"//' | sed 's/".*//')
echo "package.json version: $PKG_VERSION"

# Check README mentions this version
if ! grep -q "$PKG_VERSION" README.md 2>/dev/null; then
  echo "WARNING: README.md does not mention version $PKG_VERSION"
fi

# Check CHANGELOG has an entry for this version
if ! grep -q "$PKG_VERSION" CHANGELOG.md 2>/dev/null; then
  echo "WARNING: CHANGELOG.md has no entry for version $PKG_VERSION"
fi

步骤 7：可发现性检查

确保每个文档文件都能从 README.md 或 CLAUDE.md 找到。孤立的文档是不可见的。

检查：

• 项目中的每个 .md 文件都应通过直接或间接链接（经由其他已链接的文档）从 README.md 或 CLAUDE.md 找到
• 标记没有入站链接的孤立文档
• 建议为孤立文档添加链接的位置

**原因：**从用户的角度来看，无法找到的文档就等于不存在。每篇文档都必须能通过一到两次点击从入口找到。

步骤 8：更新 TODOS.md

根据差异更新项目的任务跟踪内容。

操作：

• 标记已完成的项目：扫描差异中已删除的 TODO/FIXME/HACK 注释，并将对应项目标记为已完成
• 标记新增的待办工作：扫描差异中新添加的 TODO/FIXME/HACK 注释，并创建新的跟踪条目
• 如果项目使用进度跟踪，则更新完成百分比

# Find new TODOs added in the diff
NEW_TODOS=$(echo "$DIFF_FULL" | grep '^+' | grep -iE 'TODO|FIXME|HACK' | grep -v '^+++' || true)
if [[ -n "$NEW_TODOS" ]]; then
  echo "New TODOs found in diff:"
  echo "$NEW_TODOS"
fi

# Find TODOs removed in the diff
REMOVED_TODOS=$(echo "$DIFF_FULL" | grep '^-' | grep -iE 'TODO|FIXME|HACK' | grep -v '^---' || true)
if [[ -n "$REMOVED_TODOS" ]]; then
  echo "Resolved TODOs (removed in diff):"
  echo "$REMOVED_TODOS"
fi

步骤 9：提交文档更改

将所有文档更改提交到当前分支，并使用文档同步摘要更新 PR 正文。

# Stage only .md files that were modified by this skill
git add *.md docs/*.md 2>/dev/null || true

# Check if there are staged changes
if git diff --cached --quiet; then
  echo "No documentation changes needed — all docs are up to date."
else
  git commit -m "docs: post-ship documentation sync

  - Auto-updated paths, counts, and version references
  - CHANGELOG entries polished for user benefit
  - Cross-doc consistency verified
  - Discoverability check passed
  "

  echo "Documentation sync committed."
fi

如果当前分支存在 PR，请更新其正文，加入文档同步部分：

# Update PR body with doc-sync summary (if PR exists)
PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || true)
if [[ -n "$PR_NUMBER" ]]; then
  echo "Updating PR #$PR_NUMBER with doc-sync summary..."
fi

集成

此技能旨在作为 flow-deliver 的子步骤运行。验证和审查完成后，调用 doc-sync，确保文档与已交付的代码保持同步。

从 flow-deliver 调用：

After PR creation and CI passes:
1. Run doc-sync to update documentation
2. Push doc changes to the PR branch
3. Re-run CI if doc changes affect tests

独立调用：

User: "sync docs"
User: "update documentation after merge"
User: "document changes from last release"