doc-maintenance

文档维护技能

检测文档偏差并通过 PR 修复——不重写，不引入不必要的改动。

使用场景

• 定期审查文档（例如每周一次或在发布后）
• 重大功能合并后
• 有人询问“我们的文档是最新的吗？”
• 有人要求审查 README / SPEC / PRODUCT 的准确性

目标文档

文档	路径	关注点
README	README.md	功能表、路线图、快速入门、“是什么”的准确性、“适用于”表格
SPEC	doc/SPEC.md	不存在错误的“不支持”声明，主要模型／架构的准确性
PRODUCT	doc/PRODUCT.md	核心概念、功能列表、原则的准确性

范围之外：DEVELOPING.md、DATABASE.md、CLI.md、doc/plans/、技能文件、 发布说明。这些面向开发者或具有时效性——引起用户困惑的风险较低。

工作流

第 1 步——检测变更

查找上次审查游标：

# Read the last-reviewed commit SHA
CURSOR_FILE=".doc-review-cursor"
if [ -f "$CURSOR_FILE" ]; then
  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
else
  # First run: look back 60 days
  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
fi

然后收集游标之后的提交：

git log "$LAST_SHA"..HEAD --oneline --no-merges

第 2 步——分类变更

扫描提交消息和变更文件。归类为：

• 功能——新增能力（关键词：feat、add、implement、support）
• 破坏性变更——移除／重命名内容（关键词：remove、breaking、drop、rename）
• 结构性变更——新目录、配置变更、新适配器、新 CLI 命令

**忽略：**重构、仅测试的变更、CI 配置、依赖升级、仅文档变更、 样式／格式调整提交。这些不会影响文档准确性。

对于难以判断的情况，检查实际差异——标题为“refactor: X”的提交 如果添加了新的公共 API，就属于功能变更。

第 3 步——汇总变更

生成简洁的列表，例如：

Since last review (<sha>, <date>):
- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
- FEATURE: Project archiving added
- BREAKING: Removed legacy webhook adapter
- STRUCTURAL: New .agents/skills/ directory convention

如果没有值得注意的变更，跳到第 7 步（更新游标并退出）。

第 4 步——审查每份目标文档

完整阅读每份目标文档，并与变更摘要交叉核对。检查以下内容：

1. 遗漏已发布功能——完全没有提及的重大已发布功能
2. 过时信息——已发布的功能仍被列为“即将推出”／“路线图”／“计划中” ／“不支持”／“待定”
3. 快速入门准确性——安装命令、先决条件和启动说明是否仍然正确（仅 README）
4. 功能表准确性——功能部分是否反映了当前能力？（仅 README）
5. 兼容性准确性——受支持的适配器／集成是否都正确列出？

使用 references/audit-checklist.md 作为结构化检查清单。 使用 references/section-map.md 了解各功能领域对应的查阅位置。

第 5 步——创建分支并应用最小改动

# Create a branch for the doc updates
BRANCH="docs/maintenance-$(date +%Y%m%d)"
git checkout -b "$BRANCH"

仅应用修复偏差所需的改动。规则：

• **仅做最小改动。**修正不准确之处，不要重写章节。
• **保持语气和风格。**符合各文档现有的语气。
• **不做外观调整。**不要修正拼写错误、重新格式化表格或重组章节， 除非这些改动属于事实修正的一部分。
• **不添加新章节。**如果某项功能需要新增完整章节，请在 PR 描述中注明后续处理——不要在维护审查中添加。
• **路线图项目：**将已发布的功能移出路线图。如果现有章节尚未提及，则在适当章节中简要提及。不要添加冗长描述。

第 6 步——创建 PR

提交变更并创建 PR：

git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
git commit -m "docs: update documentation for accuracy

- [list each fix briefly]

Co-Authored-By: Paperclip <[email protected]>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'
## Summary
Automated doc maintenance pass. Fixes documentation drift detected since
last review.

### Changes
- [list each fix]

### Change summary (since last review)
- [list notable code changes that triggered doc updates]

## Review notes
- Only factual accuracy fixes — no style/cosmetic changes
- Preserves existing voice and structure
- Larger doc additions (new sections, tutorials) noted as follow-ups

🤖 Generated by doc-maintenance skill
EOF
)"

第 7 步——更新游标

成功完成审查后（无论是否需要编辑），更新游标：

git rev-parse HEAD > .doc-review-cursor

如果进行了编辑，游标更新已提交到 PR 分支。如果不需要编辑，则将游标更新提交到当前分支。

变更分类规则

信号	类别	是否需要更新文档？
消息中包含 feat:、add、implement、support	功能	如果面向用户，则需要
消息中包含 remove、drop、breaking、!:	破坏性变更	需要
新增顶层目录或配置文件	结构性变更	可能需要
fix:、bugfix	修复	不需要（除非会改变文档中描述的行为）
refactor:、chore:、ci:、test:	维护	不需要
docs:	文档变更	不需要（已处理）
仅更新依赖项	维护	不需要

补丁风格指南

• 修正事实，不要改写措辞
• 移除路线图条目时，不要留下空缺——直接删除该条目
• 添加功能说明时，沿用周边条目的格式 （例如，如果功能采用表格列出，就添加一行表格）
• README 的更改应尽量精简——不应频繁变动
• 对于 SPEC/PRODUCT，优先更新现有描述，而不是添加新内容 （例如，将“V1 中不支持”改为“通过 X 支持”，而不是添加新章节）

输出

技能完成后，报告：

• 扫描了多少个提交
• 发现了多少项值得注意的变更
• 进行了多少处文档编辑（以及涉及哪些文件）
• PR 链接（如果进行了编辑）
• 需要进一步编写较大篇幅文档的后续事项