---

name: doc-maintenance
description: >
  审计顶层文档（README、SPEC、PRODUCT）与近期 Git 历史之间是否存在漂移——已发布的功能在文档中缺失，或文档列为"即将推出"的功能实际上已上线。提出最小修改建议，创建分支，并提交 PR。适用于被要求审核文档准确性时、重大功能合并后，或按周期执行。

---

# 文档维护技能

发现文档漂移并通过 PR 修复——不重写，不折腾。

## 适用场景

- 定期文档审核（例如每周或发布后）
- 重大功能合并后
- 被问及"我们的文档是否最新？"时
- 被要求审核 README / SPEC / PRODUCT 的准确性时

## 目标文档

| 文档 | 路径 | 关注要点 |
|----------|------|-------------|
| README | `README.md` | 功能表、路线图、快速入门、"这是什么"的准确性、"可与以下工具配合使用"的表格 |
| SPEC | `doc/SPEC.md` | 没有错误的"不支持"声明，主要模型/模式的准确性 |
| PRODUCT | `doc/PRODUCT.md` | 核心概念、功能列表、原则的准确性 |

不在范围内：DEVELOPING.md、DATABASE.md、CLI.md、doc/plans/、技能文件、发布说明。这些是面向开发者或临时性的文档——造成用户混淆的风险较低。

## 工作流程

### 步骤 1 — 检测变更内容

找到上一次审核的光标位置：

```bash
# 读取上一次审核的提交 SHA
CURSOR_FILE=".doc-review-cursor"
if [ -f "$CURSOR_FILE" ]; then
  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
else
  # 首次运行：回溯 60 天
  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
fi
```

然后收集光标位置之后的提交：

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

### 步骤 2 — 对变更分类

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

- **Feature**（新功能）—— 新的能力（关键词：`feat`、`add`、`implement`、`support`）
- **Breaking**（破坏性变更）—— 移除/重命名的内容（关键词：`remove`、`breaking`、`drop`、`rename`）
- **Structural**（结构性变更）—— 新目录、配置变更、新适配器、新 CLI 命令

**忽略：** 重构、仅测试变更、CI 配置、依赖版本更新、仅文档变更、样式/格式化提交。这些不影响文档准确性。

对于边界情况，检查实际的 diff——标题为"refactor: X"但新增了公开 API 的提交属于功能变更。

### 步骤 3 — 构建变更摘要

生成简洁列表，例如：

```
自上次审核（<sha>，<date>）以来的变更：
- FEATURE（新功能）：插件系统已合并（运行时、SDK、CLI、插槽、事件桥接）
- FEATURE（新功能）：新增项目归档功能
- BREAKING（破坏性变更）：移除了旧版 Webhook 适配器
- STRUCTURAL（结构性变更）：新增 .agents/skills/ 目录约定
```

如果没有值得注意的变更，直接跳到步骤 7（更新光标位置并退出）。

### 步骤 4 — 审核每个目标文档

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

1. **假阴性**——已发布的重要功能在文档中完全没有提及
2. **假阳性**——列为"即将推出"/"路线图"/"规划中"/"不支持"/"待定"但实际已上线的功能
3. **快速入门准确性**——安装命令、前置条件和启动说明是否仍然正确（仅 README）
4. **功能表准确性**——功能部分是否反映了当前的能力？（仅 README）
5. **"可与以下工具配合使用"的准确性**——支持的适配器/集成是否列正确？

使用 `references/audit-checklist.md` 作为结构化检查清单。
使用 `references/section-map.md` 了解每个功能区域的位置。

### 步骤 5 — 创建分支并应用最小修改

```bash
# 为文档更新创建分支
BRANCH="docs/maintenance-$(date +%Y%m%d)"
git checkout -b "$BRANCH"
```

**仅**应用修复漂移所需的修改。规则：

- **仅做最小修补。** 修复不准确之处，不要重写章节。
- **保留语气和风格。** 与每个文档的现有语气保持一致。
- **不做外观性修改。** 除非是事实性修复的一部分，否则不要修正拼写错误、重新格式化表格或重新组织章节。
- **不新增章节。** 如果一个功能需要全新的章节，在 PR 描述中将其标注为后续事项——不要在维护性检查中新增。
- **路线图条目：** 将已发布的功能移出路线图。在适当的现有章节中添加简要提及（如果还没有的话）。不要添加冗长的描述。

### 步骤 6 — 提交 PR

提交变更并打开 PR：

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

- [简要列出每个修复项]

Co-Authored-By: Paperclip <noreply@paperclip.ing>"

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 — 更新光标位置

在成功完成审核后（无论是否进行了修改），更新光标位置：

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

如果进行了修改，该操作已在 PR 分支中提交。如果不需要修改，则将光标位置更新提交到当前分支。

## 变更分类规则

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

## 修补风格指南

- 修复事实，而非文笔
- 如果移除路线图条目，不要留空——干净地删除该条目
- 如果添加功能提及，与周围条目的格式保持一致（例如，如果功能以表格形式呈现，则添加一行表格行）
- 对 README 的修改尤其要精简——它不应频繁变动
- 对于 SPEC/PRODUCT，优先更新现有语句而非新增语句（例如，将"V1 中不支持"改为"通过 X 支持"，而不是新增一个章节）

## 输出

技能完成后，报告以下内容：

- 扫描了多少个提交
- 找到了多少个值得注意的变更
- 做了多少次文档修改（以及修改了哪些文件）
- PR 链接（如果进行了修改）
- 任何需要更大文档工作的后续事项