ddev-doc-review

name	ddev-doc-review
description	文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。

文档审查

将文档审查任务派发给独立子代理，以独立视角审视文档质量，而不是让主 agent 自审自评。

⚠️ HARD GATE — 禁止主代理自审

加载本 skill 后，必须派发 General 子代理执行审查。主代理在任何情况下都禁止自行阅读文档并产出审查结论。 跳过派发 = 违规。无例外。不得因为"文档较短""只改了一点""时间紧"等理由绕过。

何时使用

• 写完 spec / design / plan 文档后，需要确认文档质量
• 代码改动完成后，需要确认关联文档是否准确反映改动
• 执行完成后，需要审查 implementation-notes.md 中 AI 自行记录的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致
• 用户要求"审查这个文档""帮我看下文档有没有问题"
• 准备合并或发布前，做文档质量门禁

核心流程

0. ⚠️ 硬门禁：主 agent 必须先 Read implementation-notes.md（如存在），了解 AI 在执行阶段的 Design Decisions / Deviations / Tradeoffs，作为审查上下文的一部分。
1. 主 agent 定位待审查的文档路径和关联的代码改动范围
2. 主 agent 读取文档和代码改动，整理审查上下文
3. ⚠️ 主 agent 必须派发 General 子代理执行审查（禁止主 agent 自行审查，见上方 HARD GATE）
4. 子代理返回审查报告
5. 主 agent 汇总问题、评估严重度、向用户呈现
6. 主 agent 在同一轮对话中立即逐项修复所有阻塞和重要问题——不得推迟到后续步骤或下一轮对话。
7. ⚠️ 写入决策文档：修复完成后，必须将本轮审查中发现的未记录决策、遗漏取舍、新偏离写入 implementation-notes.md（按 ddev-exec 的四维度格式：Design Decisions / Deviations / Tradeoffs / Open Questions）。此步骤不可跳过——即使本轮未发现新决策，也须追加一条审查轮次记录（标注"本轮无新增决策"）。
8. 审查结论判定与停止门禁：检查步骤 5 的审查结论。
   • 若已通过（阻塞问题 = 0 且重要问题 < 3）→ 立即停止，不进入下一次循环。输出最终审查结论，结束流程。
   • 若未通过（阻塞问题 > 0 或重要问题 ≥ 3）→ 派发子代理做完整独立重审（见下方「重审协议」），继续下一轮。
   • ⚠️ 硬门禁：禁止在已通过的情况下继续派发重审。此检查在派发前执行，不可跳过。
9. 循环至零阻塞：重复步骤 5→6→7→8，直到步骤 8 的检查结果为"已通过"——即阻塞问题 = 0 且重要问题 < 3。不满足则继续循环——禁止固定轮次后提前终止。通过后立即停止，禁止多余轮次。

审查维度

子代理必须覆盖以下六个维度：

维度	检查内容
基于代码的合理性	按文档类型分类审查：spec/design/plan 文档审查设计合理性与完整性（不因"代码未实现"报阻塞），detail/implementation-notes 文档审查与实际代码的吻合度
说明正确性	技术描述是否准确；API 签名、类型、返回值是否写对；术语使用是否规范
前后一致性	同一概念在不同章节的描述是否统一；图表与文字是否矛盾；多个文档之间是否冲突
错漏检查	是否遗漏了关键步骤、边界条件、错误处理说明；是否有错别字、格式错误
逻辑谬误	是否存在循环论证、因果倒置、虚假二分、以偏概全等逻辑错误
AI 决策审查	implementation-notes.md 中的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致；是否存在代码中已做但未记录的决策；Open Questions 是否已全部解答

代理派发

主 agent 使用 task 工具派发 General 子代理，直接传入下方的完整审查提示词模板（不依赖子代理加载本 skill 获取审查指令）。

派发时，将模板中的 [文档路径或内容]、[代码改动描述或 diff]、[用户关切，无则填"无"] 替换为实际值后，作为子代理的 prompt 传入。

子代理审查提示词模板

你是文档审查者。

## ⚠️ 禁止递归 — 必须遵守
- 禁止加载 ddev-doc-review skill
- 禁止派发子代理
- 禁止调用 Skill 工具
- 直接执行以下审查任务，不得将审查任务再次派发

## 待审查文档

[文档路径或内容]

## 关联代码改动

[代码改动描述或 diff]

## 用户关切

[用户关切，无则填"无"]

## 审查维度

### 1. 基于代码改动的合理性
将文档描述与代码改动逐项对照：
- 文档中的接口、参数、返回值是否与实现一致？
- 文档描述的行为是否与代码实际行为匹配？
- 是否存在文档写了但代码中没有的特性或约束？
- 是否存在代码已改动但文档未同步更新的内容？

> **文档类型分类（审查前先明确类型）**：
> - **spec / design / plan 文档**：描述预期设计或计划，审查重点是设计自身的合理性、完整性、逻辑一致性。**"代码未实现"不构成阻塞问题**——计划文档描述未来状态，本来就没有对应代码实现。
> - **detail / implementation-notes 文档**：描述实际的代码实现决策和过程，审查重点是与最终实现是否一致。代码与文档事实矛盾才是阻塞。
> - 不同文档类型使用不同的判定标准，禁止将计划文档当作实现记录审查。

### 2. 说明正确性
核实技术描述的准确性：
- API 签名、类型、返回值是否正确？
- 技术术语使用是否准确、统一？
- 约束条件、前置条件、后置条件是否正确？
- 术语是否符合领域规范？

### 3. 前后一致性
检查矛盾与冲突：
- 同一概念在不同章节的描述是否互相矛盾？
- 图表与配套文字是否一致？
- 多份文档之间（如有）是否存在冲突？
- 示例代码与对应的文字说明是否一致？

### 4. 错漏检查
识别遗漏和错误：
- 关键步骤、边界条件、错误场景是否已说明？
- 是否存在错别字、格式错误、失效引用？
- 失败模式和错误处理是否描述清楚？
- 是否存在应明确写出的隐性假设？

### 5. 逻辑谬误
检查推理错误：
- 循环论证："X 是对的，因为 X 这么说"
- 虚假二分：只给出两种选择但实际存在更多
- 相关与因果混淆：把相关性当成因果
- 以偏概全：从个别案例推广到一般结论
- 预设前提：把未经证实的假设当作论证前提

### 6. AI 决策审查
审查 `implementation-notes.md`（如存在）中 AI 自行记录的决策：
- **Design Decisions**：记录的设计决策是否与最终代码一致？是否有代码中已做但未记录的决策？
- **Deviations**：记录的偏离是否确实发生？偏离理由是否成立？是否存在未记录的偏离？
- **Tradeoffs**：记录的取舍是否与最终实现吻合？是否遗漏了重要的替代方案考量？
- **Open Questions**：是否全部已解答？未解答的问题是否会影响代码正确性？
- **产出**：审查中发现的未记录决策、遗漏取舍、新发现的偏离 → **必须写入 `implementation-notes.md`**（按 ddev-exec 的四维度格式追加），不只是标记问题

## 判定标准

**只标记会误导读者、引发实现错误或阻碍理解的问题。** 措辞偏好和风格瑕疵不算问题。
但文档与代码事实矛盾**永远是阻塞级问题**（适用于 detail/implementation-notes 文档；不适用于 plan/spec/design 文档）。

> **文档类型判定校准**：
> - **spec / design / plan 文档**：审查焦点为设计合理性、完整性、逻辑一致性。"代码与文档不符"不适用——计划文档描述未来状态，不存在对应代码实现。**禁止以"代码未修改"为由标记阻塞**。
> - **detail / implementation-notes 文档**：审查焦点为记录与实际实现的吻合度。代码与文档矛盾为阻塞。
> - 审查开始时先声明文档类型，所有问题标注以此为基准。

## 输出格式

## 文档审查报告

**审查文档：** [列表]

**关联代码改动：** [摘要]

**问题清单：**

| # | 严重度 | 位置 | 问题描述 | 建议修复 |
|---|--------|------|---------|---------|

**未记录决策（需写入 implementation-notes.md）：**

| # | 类别 | 内容 | 建议写入维度 |
|---|------|------|-------------|
|   | Design Decision / Deviation / Tradeoff / Open Question | 具体描述 | — |

> 即使本轮未发现新的未记录决策，也必须输出"本轮无新增"。

严重度定义：
- **阻塞**：文档与代码事实矛盾，会误导读者或引发实现错误
- **重要**：描述不准确、关键信息遗漏、前后矛盾
- **建议**：措辞优化、格式修正、补充说明

**审查结论：** 通过 / 需要修改

- 通过：阻塞 = 0 且重要 < 3
- 需要修改：阻塞 > 0 或重要 ≥ 3

若结论为"需要修改"，须逐项列出必须修复的内容。

输出格式

审查报告应包含：

文档审查报告
============

审查文档：[文档路径列表]
关联代码改动：[改动范围描述]

问题清单：
- [严重度] 文件:区域 — 问题描述 → 建议修复

未记录决策：
- [Design Decision/Deviation/Tradeoff/Open Question] 描述 → 建议写入位置

严重度定义：
- 阻塞：文档与代码事实矛盾，会误导读者或引发实现错误
- 重要：描述不准确、关键信息遗漏、前后矛盾
- 建议：措辞优化、格式改进、补充说明

审查结论：[通过 / 有条件通过 / 需要修改]

重审协议

修复后重新派发子代理审查时，必须遵守以下规则：

1. 从零完整审查：子代理必须覆盖全部六个审查维度，与首次审查标准相同，不可退化为仅验证上轮问题的修复状态
2. 禁止引导性提示：不得告诉子代理"上一轮发现了 N 个问题，检查是否修了"——这会让子代理退化为修复验证器，遗漏修复过程中新引入的问题
3. 传递完整上下文：向子代理传递文档路径、代码改动范围、用户关切，与首次审查的输入完全相同
4. 独立判断：子代理可能发现修复过程中新引入的问题，这正是完整重审的价值
5. 每轮写入：重审后修复时同样要将本轮新发现的未记录决策/偏离/取舍写入 implementation-notes.md，不只在首轮写

约束

• ⚠️ 主代理禁止自行审查——必须派发子代理，任何情况无例外
• ⚠️ 防递归：主代理派发子代理时必须传入上方内嵌的完整审查提示词模板（含递归禁令），禁止让子代理加载本 skill 自行获取审查指令
• 子代理必须是独立视角，不能复用主 agent 的判断
• 发现文档与代码事实矛盾时，必须标记为阻塞
• 不允许用"看起来没问题""基本正确"等模糊表述放行
• 如果缺少代码改动信息，先向用户索要，不要退化成纯文档校对
• 子代理审查报告返回后，主 agent 必须在同一轮对话中立即修复阻塞和重要问题，不得仅记录或推迟
• 修复后重审必须是完整独立审查（覆盖全部六维度），禁止退化为仅验证上轮修复点
• 审查为补充而非推翻：对 implementation-notes.md 的写入仅限于补充遗漏的决策、取舍和偏离，不得修改或推翻 spec/detail/plan 中已确定的大体路径、架构决策和核心设计。审查发现的问题修复也必须服从上游文档的既定方向