Back to Details

doc-maintenance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Doc Maintenance Skill

文档维护技能

Detect documentation drift and fix it via PR — no rewrites, no churn.
检测文档偏差并通过PR修复，无需重写内容，不会产生无效变更。

When to Use

何时使用

  • Periodic doc review (e.g. weekly or after releases)
  • After major feature merges
  • When asked "are our docs up to date?"
  • When asked to audit README / SPEC / PRODUCT accuracy
  • 定期文档审查（例如每周或版本发布后）
  • 重大功能合并后
  • 被问到「我们的文档是最新的吗？」时
  • 被要求审计README / SPEC / PRODUCT准确性时

Target Documents

目标文档

DocumentPathWhat matters
README
README.md
Features table, roadmap, quickstart, "what is" accuracy, "works with" table
SPEC
doc/SPEC.md
No false "not supported" claims, major model/schema accuracy
PRODUCT
doc/PRODUCT.md
Core concepts, feature list, principles accuracy
Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files, release notes. These are dev-facing or ephemeral — lower risk of user-facing confusion.
文档路径关注内容
README
README.md
功能列表、路线图、快速入门、「产品是什么」描述准确性、「兼容支持」列表
SPEC
doc/SPEC.md
无错误的「不支持」声明、核心模型/schema的准确性
PRODUCT
doc/PRODUCT.md
核心概念、功能列表、设计原则准确性
不涉及范围：DEVELOPING.md、DATABASE.md、CLI.md、doc/plans/、技能文件、发布说明。这些都是面向开发者或临时性的文档，引发用户侧混淆的风险较低。

Workflow

工作流程

Step 1 — Detect what changed

步骤1 — 检测变更内容

Find the last review cursor:
bash
undefined
找到上一次审查的游标：
bash
undefined

Read the last-reviewed commit SHA

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

Then gather commits since the cursor:

```bash
git log "$LAST_SHA"..HEAD --oneline --no-merges
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

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

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

Step 2 — Classify changes

步骤2 — 变更分类

Scan commit messages and changed files. Categorize into:
  • Feature — new capabilities (keywords: 
    feat
    , 
    add
    , 
    implement
    , 
    support
    )
  • Breaking — removed/renamed things (keywords: 
    remove
    , 
    breaking
    , 
    drop
    , 
    rename
    )
  • Structural — new directories, config changes, new adapters, new CLI commands
Ignore: refactors, test-only changes, CI config, dependency bumps, doc-only changes, style/formatting commits. These don't affect doc accuracy.
For borderline cases, check the actual diff — a commit titled "refactor: X" that adds a new public API is a feature.
扫描提交信息和变更文件，分为以下类别：
  • 功能类 — 新增能力（关键词：
    feat
    、
    add
    、
    implement
    、
    support
    ）
  • 破坏性变更类 — 移除/重命名的内容（关键词：
    remove
    、
    breaking
    、
    drop
    、
    rename
    ）
  • 结构类 — 新增目录、配置变更、新增适配器、新增CLI命令
忽略：重构、仅测试相关变更、CI配置、依赖升级、仅文档变更、样式/格式提交。这些内容不会影响文档准确性。
对于边界情况，请查看实际diff — 标题为「refactor: X」但新增了公共API的提交属于功能类。

Step 3 — Build a change summary

步骤3 — 生成变更摘要

Produce a concise list like:
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
If there are no notable changes, skip to Step 7 (update cursor and exit).
生成简洁的变更列表，例如：
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（更新游标并退出）。

Step 4 — Audit each target doc

步骤4 — 审计每个目标文档

For each target document, read it fully and cross-reference against the change summary. Check for:
  1. False negatives — major shipped features not mentioned at all
  2. False positives — features listed as "coming soon" / "roadmap" / "planned" / "not supported" / "TBD" that already shipped
  3. Quickstart accuracy — install commands, prereqs, and startup instructions still correct (README only)
  4. Feature table accuracy — does the features section reflect current capabilities? (README only)
  5. Works-with accuracy — are supported adapters/integrations listed correctly?
Use 
references/audit-checklist.md
as the structured checklist. Use 
references/section-map.md
to know where to look for each feature area.
通读每个目标文档，与变更摘要交叉核对，检查以下内容：
  1. 漏报 — 已上线的核心功能完全未提及
  2. 误报 — 标记为「即将上线」/「路线图」/「规划中」/「不支持」/「待补充」的功能实际已经发布
  3. 快速入门准确性 — 安装命令、前置依赖、启动说明仍然正确（仅README需要检查）
  4. 功能列表准确性 — 功能部分是否反映了当前的能力（仅README需要检查）
  5. 兼容性准确性 — 支持的适配器/集成是否正确列出
使用
references/audit-checklist.md
作为结构化检查清单，使用
references/section-map.md
定位每个功能领域对应的文档位置。

Step 5 — Create branch and apply minimal edits

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

bash
undefined
bash
undefined

Create a branch for the doc updates

Create a branch for the doc updates

BRANCH="docs/maintenance-$(date +%Y%m%d)" git checkout -b "$BRANCH"

Apply **only** the edits needed to fix drift. Rules:

- **Minimal patches only.** Fix inaccuracies, don't rewrite sections.
- **Preserve voice and style.** Match the existing tone of each document.
- **No cosmetic changes.** Don't fix typos, reformat tables, or reorganize
  sections unless they're part of a factual fix.
- **No new sections.** If a feature needs a whole new section, note it in the
  PR description as a follow-up — don't add it in a maintenance pass.
- **Roadmap items:** Move shipped features out of Roadmap. Add a brief mention
  in the appropriate existing section if there isn't one already. Don't add
  long descriptions.
BRANCH="docs/maintenance-$(date +%Y%m%d)" git checkout -b "$BRANCH"

**仅**应用修复文档偏差所需的改动，规则如下：

- **仅提交最小补丁**：修正不准确的内容，不要重写段落
- **保留语调和风格**：匹配每个文档现有的语气风格
- **无样式改动**：不要修改错别字、重新格式化表格、或重构段落，除非这些属于事实修正的一部分
- **不新增章节**：如果某个功能需要新增完整章节，请在PR描述中注明作为后续优化项，不要在本次维护中添加
- **路线图项处理**：将已发布的功能从路线图中移除，如果现有段落中没有相关提及，可以在合适的现有段落中添加简短说明，不要添加长描述

Step 6 — Open a PR

步骤6 — 提交PR

Commit the changes and open a PR:
bash
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 <noreply@paperclip.ing>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'
提交变更并创建PR：
bash
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 <noreply@paperclip.ing>"

git push -u origin "$BRANCH"

gh pr create \
  --title "docs: periodic documentation accuracy update" \
  --body "$(cat <<'EOF'

Summary

Summary

Automated doc maintenance pass. Fixes documentation drift detected since last review.
Automated doc maintenance pass. Fixes documentation drift detected since last review.

Changes

Changes

  • [list each fix]
  • [list each fix]

Change summary (since last review)

Change summary (since last review)

  • [list notable code changes that triggered doc updates]
  • [list notable code changes that triggered doc updates]

Review notes

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 )"
undefined
  • 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 )"
undefined

Step 7 — Update the cursor

步骤7 — 更新游标

After a successful audit (whether or not edits were needed), update the cursor:
bash
git rev-parse HEAD > .doc-review-cursor
If edits were made, this is already committed in the PR branch. If no edits were needed, commit the cursor update to the current branch.
审计完成后（无论是否需要修改文档），更新游标：
bash
git rev-parse HEAD > .doc-review-cursor
如果有做修改，游标更新已经包含在PR分支的提交中。如果不需要修改，直接在当前分支提交游标更新。

Change Classification Rules

变更分类规则

SignalCategoryDoc update needed?
feat:
, 
add
, 
implement
, 
support
in message		FeatureYes if user-facing
remove
, 
drop
, 
breaking
, 
!:
in message		BreakingYes
New top-level directory or config fileStructuralMaybe
fix:
, 
bugfix
FixNo (unless it changes behavior described in docs)
refactor:
, 
chore:
, 
ci:
, 
test:
MaintenanceNo
docs:
Doc changeNo (already handled)
Dependency bumps onlyMaintenanceNo
信号分类是否需要更新文档？
提交信息包含
feat:
、
add
、
implement
、
support
功能类如果是面向用户的功能则需要
提交信息包含
remove
、
drop
、
breaking
、
!:
破坏性变更类是
新增顶层目录或配置文件结构类可能需要
fix:
、
bugfix
修复类否（除非变更了文档中描述的行为）
refactor:
、
chore:
、
ci:
、
test:
维护类否
docs:
文档变更否（已经处理）
仅依赖升级维护类否

Patch Style Guide

补丁风格指南

  • Fix the fact, not the prose
  • If removing a roadmap item, don't leave a gap — remove the bullet cleanly
  • If adding a feature mention, match the format of surrounding entries (e.g. if features are in a table, add a table row)
  • Keep README changes especially minimal — it shouldn't churn often
  • For SPEC/PRODUCT, prefer updating existing statements over adding new ones (e.g. change "not supported in V1" to "supported via X" rather than adding a new section)
  • 只修正事实错误，不修改行文措辞
  • 如果移除路线图项，不要留下空白，干净删除对应条目即可
  • 如果添加功能提及，匹配周边条目的格式（例如功能放在表格中，就新增一行表格）
  • 尽量减少README的变更，它不应该频繁变动
  • 对于SPEC/PRODUCT，优先更新现有描述，而非新增内容（例如将「V1版本不支持」修改为「可通过X支持」，而不是新增一个章节）

Output

输出

When the skill completes, report:
  • How many commits were scanned
  • How many notable changes were found
  • How many doc edits were made (and to which files)
  • PR link (if edits were made)
  • Any follow-up items that need larger doc work
技能执行完成后，输出以下内容：
  • 扫描的提交数量
  • 发现的值得关注的变更数量
  • 文档修改次数（以及修改了哪些文件）
  • PR链接（如果有修改的话）
  • 需要更大范围文档工作的后续事项