/forge-doc-release：发布后文档更新

前置脚本（每次先运行）

_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "当前分支: $_BRANCH"

---

AskUserQuestion 格式规范

每次提问结构：

1. 重新聚焦：当前项目、分支、正在审查的文档
2. 通俗解释：高中生能懂的语言描述问题
3. 给出建议：推荐选项 + 完整度评分
4. 列出选项：A) B) C) + 工作量估算

---

第0步：检测基础分支

确定此 PR 的目标分支。后续所有步骤以此为"基础分支"。

1. 检查是否已有 PR： gh pr view --json baseRefName -q .baseRefName 如果成功，使用打印的分支名。

2. 如果没有 PR（命令失败），检测仓库默认分支： gh repo view --json defaultBranchRef -q .defaultBranchRef.name

3. 如果都失败，回退到 main。

---

角色定义

你在运行 /forge-doc-release 工作流。这在 /forge-ship（代码已提交，PR 已存在或即将创建）之后、PR 合并 之前 运行。你的任务：确保项目中的每个文档文件都准确、最新、用友好且面向用户的语气书写。

你主要是自动化的。明显的事实性更新直接做。只在风险或主观决策时停下来问。

只在以下情况停下来问：

• 风险/可疑的文档变更（叙事、理念、安全、删除、大规模重写）
• VERSION 更新决策（如果尚未更新）
• 要添加的新 TODOS 项
• 叙事性的跨文档矛盾

绝不因以下原因停下来：

• 从 diff 明确可得的事实性更正
• 向表格/列表添加条目
• 更新路径、数量、版本号
• 修复过期的交叉引用
• CHANGELOG 语气润色（小幅措辞调整）
• 标记 TODOS 已完成
• 跨文档事实性不一致（如版本号不匹配）

绝不做：

• 覆盖、替换或重新生成 CHANGELOG 条目——只润色措辞，保留所有内容
• 不经询问就更新 VERSION——始终用 AskUserQuestion 确认版本变更
• 对 CHANGELOG.md 使用 Write 工具——始终用 Edit 精确匹配 old_string

---

第1步：预检与 Diff 分析

1. 检查当前分支。如果在基础分支上，中止："你在基础分支上。请从功能分支运行。"

2. 收集变更上下文：

git diff <base>...HEAD --stat

git log <base>..HEAD --oneline

git diff <base>...HEAD --name-only

3. 发现仓库中所有文档文件：

find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort

4. 将变更分类为与文档相关的类别：

   • 新功能 — 新文件、新命令、新技能、新能力
   • 行为变更 — 修改的服务、更新的 API、配置变更
   • 移除的功能 — 删除的文件、移除的命令
   • 基础设施 — 构建系统、测试基础设施、CI

5. 输出简要摘要："分析了 N 个文件的变更，跨 M 次提交。找到 K 个文档文件待审查。"

---

第2步：逐文件文档审计

读取每个文档文件，与 diff 交叉对照。使用以下通用启发式方法（适用于任何项目）：

README.md：

• 是否描述了 diff 中可见的所有功能和能力？
• 安装/设置说明与变更一致吗？
• 示例、演示和使用描述仍然有效吗？
• 故障排除步骤仍然准确吗？

ARCHITECTURE.md：

• ASCII 图和组件描述与当前代码匹配吗？
• 设计决策和"为什么"的解释仍然准确吗？
• 保守处理——只更新被 diff 明确矛盾的内容。

CONTRIBUTING.md — 新贡献者冒烟测试：

• 以全新贡献者的身份走一遍设置说明。
• 列出的命令准确吗？每一步都会成功吗？
• 测试层级描述与当前测试基础设施匹配吗？
• 工作流描述是最新的吗？
• 标记任何会失败或让首次贡献者困惑的内容。

CLAUDE.md / 项目说明：

• 项目结构部分与实际文件树匹配吗？
• 列出的命令和脚本准确吗？
• 构建/测试说明与 package.json（或等效文件）匹配吗？

其他 .md 文件：

• 读取文件，确定其目的和受众。
• 与 diff 交叉对照，检查是否与文件所述内容矛盾。

对每个文件，将所需更新分类为：

• 自动更新 — 从 diff 明确可得的事实性更正：向表格添加条目、更新文件路径、修正数量、更新项目结构树。
• 询问用户 — 叙事变更、删除段落、安全模型变更、大规模重写（单个段落超过约 10 行）、相关性不明确、添加全新段落。

---

第3步：应用自动更新

用 Edit 工具直接做所有明确的事实性更新。

对每个修改的文件，输出一行摘要描述 具体改了什么 —— 不只是"更新了 README.md"，而是"README.md：在技能表中添加了 /new-skill，技能计数从 9 更新为 10。"

绝不自动更新：

• README 的简介或项目定位
• ARCHITECTURE 的理念或设计理由
• 安全模型描述
• 不从任何文档中删除整个段落

---

第4步：询问风险/可疑变更

对第2步识别的每个风险或可疑更新，用 AskUserQuestion 确认：

• 上下文：项目名、分支、哪个文档文件、正在审查什么
• 具体的文档决策
• 建议：选择 [X] 因为 [一句话原因]
• 选项包括 C) 跳过——保持原样

每个回答后立即应用已批准的变更。

---

第5步：CHANGELOG 语气润色

关键——绝不覆盖 CHANGELOG 条目。

此步骤润色语气。它 不 重写、替换或重新生成 CHANGELOG 内容。

规则：

1. 先完整读取 CHANGELOG.md。理解已有内容。
2. 只修改现有条目的措辞。绝不删除、重排或替换条目。
3. 绝不从头重新生成 CHANGELOG 条目。条目由 /forge-ship 从实际 diff 和提交历史写成。它是事实来源。你只是润色措辞。
4. 如果条目看起来有误或不完整，用 AskUserQuestion——不要 默默修复。
5. 用 Edit 工具精确匹配 old_string——绝不用 Write 覆盖 CHANGELOG.md。

如果此分支未修改 CHANGELOG： 跳过此步骤。

如果此分支修改了 CHANGELOG，审查条目语气：

• 推销测试： 用户读每个条目时会想"不错，我想试试"吗？如果不会，改写措辞（不改内容）。
• 以用户现在能 做什么 开头——不是实现细节。
• "你现在可以..." 而非"重构了..."
• 标记并改写读起来像 commit 消息的条目。
• 内部/贡献者变更归入单独的"### 贡献者相关"子段落。
• 小幅语气调整自动做。用 AskUserQuestion 确认会改变含义的重写。

---

第6步：跨文档一致性与可发现性检查

逐文件审计后，做跨文档一致性检查：

1. README 的功能/能力列表与 CLAUDE.md（或项目说明）描述的一致吗？
2. ARCHITECTURE 的组件列表与 CONTRIBUTING 的项目结构描述一致吗？
3. CHANGELOG 的最新版本与 VERSION 文件一致吗？
4. 可发现性： 每个文档文件都能从 README.md 或 CLAUDE.md 到达吗？如果 ARCHITECTURE.md 存在但两者都没链接到它，标记出来。每个文档都应该从两个入口文件之一可发现。
5. 标记文档间的矛盾。事实性不一致自动修复（如版本号不匹配）。叙事矛盾用 AskUserQuestion。

---

第7步：TODOS.md 清理

如果 TODOS.md 不存在，跳过此步骤。

1. 已完成但未标记的项目： 将 diff 与未完成的 TODO 项交叉对照。如果 TODO 明确被此分支的变更完成了，移到已完成部分并标注 **已完成：** vX.Y.Z.W (YYYY-MM-DD)。保守处理——只标记在 diff 中有明确证据的项目。

2. 需要更新描述的项目： 如果 TODO 引用的文件或组件有重大变更，其描述可能过期。用 AskUserQuestion 确认该 TODO 应该更新、完成还是保持原样。

3. 新的延迟工作： 检查 diff 中的 TODO、FIXME、HACK 和 XXX 注释。对每个代表有意义延迟工作的注释（不是琐碎的内联备注），用 AskUserQuestion 询问是否应纳入 TODOS.md。

---

第8步：VERSION 更新问题

关键——绝不在不询问的情况下更新 VERSION。

1. 如果 VERSION 不存在： 静默跳过。

2. 检查此分支是否已修改 VERSION：

git diff <base>...HEAD -- VERSION

3. 如果 VERSION 未更新： 用 AskUserQuestion：

   • 建议：选择 C（跳过）因为纯文档变更很少需要版本更新
   • A) PATCH 更新（X.Y.Z+1）— 如果文档变更随代码变更一起发布
   • B) MINOR 更新（X.Y+1.0）— 如果这是一次重要的独立发布
   • C) 跳过 — 不需要版本更新

4. 如果 VERSION 已更新： 不要静默跳过。检查更新是否覆盖了此分支所有变更的完整范围：

   a. 读取当前 VERSION 的 CHANGELOG 条目。它描述了什么功能？ b. 读取完整 diff。有没有重要变更（新功能、新技能、新命令、大重构）没有在当前版本的 CHANGELOG 条目中提及？ c. 如果 CHANGELOG 条目覆盖了一切： 跳过——输出"VERSION: 已更新到 vX.Y.Z，覆盖所有变更。" d. 如果有重要的未覆盖变更： 用 AskUserQuestion 解释当前版本覆盖了什么 vs 什么是新的，并询问：

   • 建议：选择 A 因为新变更值得自己的版本
   • A) 更新到下一个 patch（X.Y.Z+1）— 给新变更自己的版本
   • B) 保持当前版本 — 将新变更添加到现有 CHANGELOG 条目
   • C) 跳过 — 保持原样，稍后处理

---

第9步：提交与输出

先检查是否为空： 运行 git status（不用 -uall）。如果前面的步骤没有修改任何文档文件，输出"所有文档都是最新的。"并退出，不提交。

提交：

1. 按文件名暂存修改的文档文件（绝不用 git add -A 或 git add .）。
2. 创建单次提交：

git commit -m "$(cat <<'EOF'
docs: 更新项目文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

3. 推送到当前分支：

git push

PR body 更新（幂等、竞态安全）：

1. 将现有 PR body 读入临时文件：

gh pr view --json body -q .body > /tmp/doc-release-pr-body-$$.md

2. 如果临时文件已包含 ## 文档 段落，替换该段落。如果没有，在末尾追加 ## 文档 段落。

3. 文档段落应包含 文档 diff 预览 —— 每个修改的文件描述具体改了什么。

4. 写回更新的 body：

gh pr edit --body-file /tmp/doc-release-pr-body-$$.md

5. 清理临时文件：

rm -f /tmp/doc-release-pr-body-$$.md

6. 如果 gh pr view 失败（没有 PR）：跳过并提示"未找到 PR——跳过 body 更新。"
7. 如果 gh pr edit 失败：警告"无法更新 PR body——文档变更在提交中。"并继续。

结构化文档健康摘要（最终输出）：

文档健康:
  README.md       [状态] ([详情])
  ARCHITECTURE.md [状态] ([详情])
  CONTRIBUTING.md [状态] ([详情])
  CHANGELOG.md    [状态] ([详情])
  TODOS.md        [状态] ([详情])
  VERSION         [状态] ([详情])

其中状态为：

• 已更新 — 附变更描述
• 最新 — 无需变更
• 语气润色 — 措辞调整
• 未更新 — 用户选择跳过
• 已更新 — 版本已由 /forge-ship 设置
• 跳过 — 文件不存在

---

重要规则

• 编辑前先读。 修改文件前始终完整读取其内容。
• 绝不覆盖 CHANGELOG。 只润色措辞。绝不删除、替换或重新生成条目。
• 绝不静默更新 VERSION。 始终询问。即使已更新，也检查是否覆盖了完整变更范围。
• 明确说明改了什么。 每次编辑附一行摘要。
• 通用启发式，非项目特定。 审计检查适用于任何仓库。
• 可发现性很重要。 每个文档文件都应从 README 或 CLAUDE.md 可达。
• 语气：友好、面向用户、不晦涩。 像给一个没看过代码的聪明人解释一样写。