doc-updates

文档更新工作流

何时使用

当代码变更需要更新 README、计划、Wiki 或文档字符串时，使用此技能。先运行 Skill(sanctum:git-workspace-review)，以记录变更上下文。

系统功能

文档更新工作流包含多项专门功能。它通过整合检测来识别冗余，并强制执行目录专属的样式规则：对 docs/ 采用严格限制，对 book/ 目录则相对宽松。系统还会验证版本号和组件数量的准确性，并在受支持的 Claude Code 版本中集成 LSP，以进行语义文档验证。

何时不使用

• README 专项更新——改用 update-readme
• 复杂的多文件整合——改用 doc-consolidation

必需的进度项

1. doc-updates:context-collected - Git 上下文 + CHANGELOG 审查
2. doc-updates:targets-identified
3. doc-updates:consolidation-checked（可跳过）
4. doc-updates:edits-applied
5. doc-updates:guidelines-verified
6. doc-updates:slop-scanned - 通过 scribe 检测 AI 标记
7. doc-updates:plugins-synced - plugin.json ↔ 磁盘审计
8. doc-updates:capabilities-synced - plugin.json ↔ 文档同步
9. doc-updates:accuracy-verified
10. doc-updates:preview

第 1 步：收集上下文（context-collected）

• 验证是否已运行 Skill(sanctum:git-workspace-review)。
• 使用其中的记录来了解变更内容。
• 确定需要更新文档的功能或错误修复。

CHANGELOG 参考（对版本同步至关重要）：

# Check recent CHANGELOG entries for undocumented features
head -100 CHANGELOG.md

# Compare documented version vs plugin versions
grep -E "^\[.*\]" CHANGELOG.md | head -3
for p in plugins/*/.claude-plugin/plugin.json; do
    jq -r '"\(.name): \(.version)"' "$p"
done | head -5

将 CHANGELOG 条目与以下内容交叉核对：

• book/src/reference/capabilities-reference.md - 所有技能/命令/Agent
• 插件文档，位于 book/src/plugins/ - 各插件文档
• 插件 README - 快速参考文档

第 2 步：确定目标（targets-identified）

• 列出所有文档位置中与范围相关的文件：
  • docs/ - 参考文档（严格样式）
  • book/ - 技术书籍内容（宽松样式）
  • 项目根目录和插件根目录中的 README.md 文件
  • 存在时的 wiki/ 条目
  • 代码文件中的文档字符串
• 优先更新面向用户的文档，然后再更新辅助计划和规范。
• 计划开展架构工作时，确认 wiki/architecture/ 中（或 ADR 所在位置）是否已有架构决策记录（ADR）。
• 开始任何实现之前，将缺失的 ADR 加入目标列表。

第 2.5 步：检查整合情况（consolidation-checked）

加载：@modules/consolidation-integration.md

目的：在编辑前检测冗余和内容臃肿。

扫描以下内容：

• 未跟踪的报告（全大写的 _REPORT.md、_ANALYSIS.md 文件）
• 臃肿的已提交文档（docs/ 中超过 500 行、book/ 中超过 1000 行的文件）
• 过时文件（应删除的过时内容）

以下操作需事先获得用户批准：

• 将一个文件的内容合并到另一个文件
• 删除过时或冗余的文件
• 拆分臃肿的文件

跳过选项：

• 使用 --skip-consolidation 标志跳过此阶段
• 选择特定项目，而不是处理全部项目

退出标准：用户已批准或跳过所有整合机会。

第 3 步：应用编辑（edits-applied）

• 使用有依据的措辞更新每个文件，说明变更内容及原因。
• 尽可能注明具体命令、文件名或配置选项。
• 文档字符串使用祈使语气，并保持简洁。
• ADR 的完整模板结构、状态流程、不可变规则和最佳实践，请参阅 modules/adr-patterns.md。

第 4 步：执行规范（guidelines-verified）

加载：@modules/directory-style-rules.md

风格规范

应用目录专属规则，保持文档风格一致。系统会检查并删除 “in order to” 或 “it should be noted” 等填充短语，并确保技术文档正文中不含表情符号。使用有具体依据的语言，明确引用具体内容，避免含糊的说法；说明操作时使用祈使语气。列表包含三项或更多内容时，优先使用项目符号，避免写成段落，以便快速浏览。

审查会对超出长度限制的段落或超过既定行数阈值的文件发出警告。我们还会标记营销用语以及 “capable” 或 “smooth” 等抽象形容词，以保持所有项目文档的技术性和直接风格。

第 4.25 步：AI 生成内容检测（slop-scanned）

对编辑后的文档运行 Skill(scribe:slop-detector)，检测 AI 生成内容的标记。

Scribe 集成

Scribe 插件提供全面的 AI 生成内容检测：

Skill(scribe:slop-detector) --target [edited-files]

检测内容包括：

• Tier 1 词语：delve、tapestry、comprehensive、leveraging 等
• 短语模式：“In today's fast-paced world”、“cannot be overstated”
• 结构标记：过度使用长破折号、项目符号、句式过于统一
• 谄媚短语：“I'd be happy to”、“Great question!”
• 标点替代写法：空格分隔的 --、用 + 表示 “and”、分号拼接句子
• 对比式否定：“It's not X, it's Y”、“X, not Y”、“, not just Y”
• 后果尾句：连续陈述事实后接 “, so the ...”，且每 1000 词的密度读数高于 2.0
• 过度解释的修正和负面表述：“in order to”、“this ensures that”、“not uncommon”，以及每个文件的否定密度读数

一条命令即可定位每项发现及其所在文件和行号，也包括选择启用和低置信度类别：

uv run --with pyyaml python scripts/slop_score.py --audit <edited-files>

编辑过的 .py 文件也要列入其中。评分器会将 Python 路径作为注释和文档字符串来读取，并保留行号，因此发现项会标出需要查看的行。符号表示法不属于散文：映射表中的箭头、公式中的加号，以及因代码会匹配某个字符而将其引起来的字符，都属于恰好出现在文档字符串中的代码。

读者定位

重写文档前，先明确读者是谁。每份正在维护的文档都有明确或默认的读者，忽略读者进行编辑会让文档逐渐变得不适合任何人阅读。

Skill(scribe:slop-detector)   # module: audience-targeting.md

• 如果文档声明了读者层级，请据此确定。如果没有声明，请根据文档所在位置推断层级（README 和入门指南属于 newcomer；插件指南属于 practitioner；ADR 和深入解析属于 expert），然后在变更摘要中说明这一推断，以便审阅者纠正。如果无法根据文档位置判断，请提问，不要猜测。
• 按章节应用删减测试：保留读者行动前需要了解的内容；链接到他们之后需要的内容；提取仅较高层级读者需要的内容；删除所有层级读者都不需要的内容。
• 提取内容，而不是删除内容。与读者层级不匹配的材料，应移至技能对应的 modules/<topic>.md，或仓库文档对应的 docs/deep-dive/<topic>.md，并在父文档开头加一行链接，说明内容面向哪些读者。
• 在 newcomer 文档中加入 expert 级别的细节，是最常见的偏离读者定位问题。入门页面正是这样每次多加一段看似合理的内容，最终变成参考手册的。

创意输出不适用此规则。audience-targeting.md 明确将 scribe:voice-* 和 session-to-post 排除在适用范围之外。

写作风格指南

为提升写作质量，请检查 elements-of-style:writing-clearly-and-concisely：

# If superpowers/elements-of-style is installed:
Skill(elements-of-style:writing-clearly-and-concisely)

# Fallback if not installed - use scribe:doc-generator principles:
Skill(scribe:doc-generator) --remediate

备用指南提供同等指导：

1. 用具体细节为每项主张提供依据
2. 删去修辞性套话（避免公式化的开头和结尾）
3. 使用数字、命令和文件名，少用形容词
4. 平衡项目符号和叙述性文字
5. 展现作者的观点（权衡、推理）

修正

如果 slop score 超过 2.5（中等），请运行：

Agent(scribe:doc-editor) --target [file]

这会提供交互式的逐节清理，并在清理前征求用户同意。

跳过选项

• 使用 --skip-slop 标志跳过 slop 检测
• 默认情况下，slop 警告不会阻止流程

第 4.5 步：同步插件注册信息（plugins-synced）

根据磁盘上的文件审计 plugin.json 文件（防止注册信息漂移）：

# Quick discrepancy check for all plugins
for plugin in plugins/*/; do
  name=$(basename "$plugin")
  pjson="$plugin/.claude-plugin/plugin.json"
  [ -f "$pjson" ] || continue

  # Count commands
  json_cmds=$(jq -r '.commands | length' "$pjson" 2>/dev/null || echo 0)
  disk_cmds=$(ls "$plugin/commands/"*.md 2>/dev/null | wc -l)

  # Count skills (directories only)
  json_skills=$(jq -r '.skills | length' "$pjson" 2>/dev/null || echo 0)
  disk_skills=$(ls -d "$plugin/skills"/*/ 2>/dev/null | wc -l)

  # Report mismatches
  if [ "$json_cmds" != "$disk_cmds" ] || [ "$json_skills" != "$disk_skills" ]; then
    echo "$name: commands=$json_cmds/$disk_cmds skills=$json_skills/$disk_skills"
  fi
done

如果发现不匹配：运行 /update-plugins --fix，或手动更新 plugin.json 文件。

这为什么重要：未注册的命令/技能不会显示在 Claude Code 的斜杠命令菜单中，也无法被发现。

第 4.75 步：同步功能文档（capabilities-synced）

加载：@modules/capabilities-sync.md

目的：确保 plugin.json 中的注册信息已反映在参考文档中。

同步目标：

来源	文档目标
plugin.json.skills[]	book/src/reference/capabilities-reference.md
plugin.json.commands[]	book/src/reference/capabilities-reference.md
plugin.json.agents[]	book/src/reference/capabilities-reference.md
hooks/hooks.json	book/src/reference/capabilities-reference.md
插件是否存在	book/src/plugins/{plugin}.md

快速检查：

# Compare registered vs documented skills
for pjson in plugins/*/.claude-plugin/plugin.json; do
  plugin=$(basename $(dirname $(dirname "$pjson")))
  jq -r --arg p "$plugin" '.skills[]? | sub("^\\./skills/"; "") | "\($p):\(.)"' "$pjson" 2>/dev/null
done | sort > /tmp/registered-skills.txt

grep -E "^\| \`[a-z-]+\` \|" book/src/reference/capabilities-reference.md | \
  head -120 | awk -F'|' '{print $2":"$3}' | sort > /tmp/documented-skills.txt

# Show missing
comm -23 /tmp/registered-skills.txt /tmp/documented-skills.txt

如果发现差异：

1. 文档中缺少内容：将条目添加到 capabilities-reference.md 表格中
2. 缺少插件页面：创建 book/src/plugins/{plugin}.md
3. SUMMARY 中缺少内容：将插件添加到 book/src/SUMMARY.md

自动生成条目的格式：

| `{skill-name}` | [{plugin}](../plugins/{plugin}.md) | {description} |

跳过选项：使用 --skip-capabilities 跳过此阶段。

第 5 步：验证准确性（accuracy-verified）

加载：@modules/accuracy-scanning.md

根据代码库验证声明：

# Quick version check
for p in plugins/*/.claude-plugin/plugin.json; do
    jq -r '"\(.name): \(.version)"' "$p"
done

# Quick counts
echo "Plugins: $(ls -d plugins/*/.claude-plugin/plugin.json | wc -l)"
echo "Skills: $(find plugins/*/skills -name 'SKILL.md' | wc -l)"

**验证：**运行带有 --help 标志的命令，以确认其可用性。

标记不匹配项：

• 与 plugin.json 不一致的版本号
• 与实际目录不一致的插件/技能/命令数量
• 不存在的文件路径

LSP 增强验证（2.0.74+）：

设置 ENABLE_LSP_TOOL=1 后，可通过语义分析增强准确性验证：

1. API 文档覆盖率：

   • 通过 LSP 查询所有公共函数/类
   • 检查哪些内容缺少文档
   • 验证所有导出项都有文档说明

2. 签名验证：

   • 比较文档中记录的函数签名与实际代码
   • 检测参数不匹配
   • 标记返回类型差异

3. 引用查找：

   • 使用 LSP 查找文档中所述项目的所有用法
   • 在文档中加入真实用法示例
   • 验证交叉引用是否准确

4. 代码结构验证：

   • 检查文档中记录的文件路径是否存在（通过 LSP 定义）
   • 验证模块组织是否与文档一致
   • 检测已重命名/移动的项目

效率：LSP 查询（50ms）与手动追踪文件（数分钟）相比，可大幅加快验证速度。

默认策略：文档更新应在所有验证任务中优先使用 LSP。永久启用 ENABLE_LSP_TOOL=1，以获得最佳效果。

非阻塞：警告仅供参考；是否修复由用户决定。

第 6 步：预览更改（preview）

• 显示每个已编辑文件的差异（git diff <file> 或 rg 片段）。
• 如果有准确性警告，请一并列出。
• 总结：
  • 新建/修改/删除的文件
  • 已执行的整合操作
  • 已修复的风格违规
  • 尚未处理的 TODO 或后续事项

退出标准

• 所有进度项均已完成，文档也已更新。
• 如有新的 ADR，应放在 wiki/architecture/（或既定的 ADR 目录）中，并标注正确的状态以及相关工作的链接。
• 符合目录特定的风格规则。
• 每份已编辑的文档都声明了或通过推断确定了受众层级，且没有任何章节面向不同的层级。
• 非目标层级的内容已提取到 modules/ 或 docs/deep-dive/ 并添加链接，绝不为满足层级要求而删除。
• 已处理或确认准确性警告。
• 内容读起来不像 AI 生成。
• 文件已暂存或已准备好供审阅。

标志

标志	效果
--skip-consolidation	跳过第 2.5 阶段的整合检查
--skip-slop	跳过第 4.25 阶段的 AI 赘述检测
--strict	将所有警告视为错误
--book-style	对所有文件应用 book/ 规则

故障排除

常见问题

文档不同步 运行 make docs-sync-check，确认功能文档仍与插件注册信息一致

构建失败 检查是否已安装所有必需的依赖项

链接失效 检查文档文件中的相对路径