菜单
文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
在当前会话里按已写好的实现计划顺序执行任务时使用
在已有规格或多步骤任务需求、且在动代码之前使用。若上游 ddev-pc-test 已产出测试用例，自动走 TDD 流程：先实现测试 demo 代码（红灯），再实现被测代码（绿灯），测试覆盖不到的部分直接开发。
代码修改场景下，spec 文档确认后，需要继续以图优先方式梳理结构体定义、数据流和流程时使用
在代码修改前需要编写 spec 文档且应优先用图表达边界、入口、流程和改动关系时使用（仅限代码改动场景，非项目级架构文档初始化）
在代码实现完成后、准备结束任务或进入发布前使用，用来核对代码实现是否与 spec 文档以及 detail 文档一致，并通过代码质量审查、清理、编码规范和注释审查后给出最终验收结论
当需要基于仓库代码推导刷写参数，并复用统一流程完成固件探测、分包或刷写时使用。
| name | ddev-doc-review |
| description | 文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。 |
将文档审查任务派发给独立子代理，以独立视角审视文档质量，而不是让主 agent 自审自评。
⚠️ HARD GATE — 禁止主代理自审
加载本 skill 后，必须派发 General 子代理执行审查。主代理在任何情况下都禁止自行阅读文档并产出审查结论。 跳过派发 = 违规。无例外。不得因为"文档较短""只改了一点""时间紧"等理由绕过。
implementation-notes.md 中 AI 自行记录的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致Read implementation-notes.md（如存在），了解 AI 在执行阶段的 Design Decisions / Deviations / Tradeoffs，作为审查上下文的一部分。implementation-notes.md（按 ddev-exec 的四维度格式：Design Decisions / Deviations / Tradeoffs / Open Questions）。此步骤不可跳过——即使本轮未发现新决策，也须追加一条审查轮次记录（标注"本轮无新增决策"）。子代理必须覆盖以下六个维度：
| 维度 | 检查内容 |
|---|---|
| 基于代码的合理性 | 文档描述是否与对应代码改动匹配；接口、参数、行为描述是否与实现一致 |
| 说明正确性 | 技术描述是否准确；API 签名、类型、返回值是否写对；术语使用是否规范 |
| 前后一致性 | 同一概念在不同章节的描述是否统一；图表与文字是否矛盾；多个文档之间是否冲突 |
| 错漏检查 | 是否遗漏了关键步骤、边界条件、错误处理说明；是否有错别字、格式错误 |
| 逻辑谬误 | 是否存在循环论证、因果倒置、虚假二分、以偏概全等逻辑错误 |
| AI 决策审查 | implementation-notes.md 中的 Design Decisions / Deviations / Tradeoffs 是否与最终代码一致；是否存在代码中已做但未记录的决策；Open Questions 是否已全部解答 |
主 agent 使用 task 工具派发 General 子代理，直接传入下方的完整审查提示词模板（不依赖子代理加载本 skill 获取审查指令）。
派发时，将模板中的 [文档路径或内容]、[代码改动描述或 diff]、[用户关切，无则填"无"] 替换为实际值后，作为子代理的 prompt 传入。
你是文档审查者。
## ⚠️ 禁止递归 — 必须遵守
- 禁止加载 ddev-doc-review skill
- 禁止派发子代理
- 禁止调用 Skill 工具
- 直接执行以下审查任务，不得将审查任务再次派发
## 待审查文档
[文档路径或内容]
## 关联代码改动
[代码改动描述或 diff]
## 用户关切
[用户关切，无则填"无"]
## 审查维度
### 1. 基于代码改动的合理性
将文档描述与代码改动逐项对照：
- 文档中的接口、参数、返回值是否与实现一致？
- 文档描述的行为是否与代码实际行为匹配？
- 是否存在文档写了但代码中没有的特性或约束？
- 是否存在代码已改动但文档未同步更新的内容？
### 2. 说明正确性
核实技术描述的准确性：
- API 签名、类型、返回值是否正确？
- 技术术语使用是否准确、统一？
- 约束条件、前置条件、后置条件是否正确？
- 术语是否符合领域规范？
### 3. 前后一致性
检查矛盾与冲突：
- 同一概念在不同章节的描述是否互相矛盾？
- 图表与配套文字是否一致？
- 多份文档之间（如有）是否存在冲突？
- 示例代码与对应的文字说明是否一致？
### 4. 错漏检查
识别遗漏和错误：
- 关键步骤、边界条件、错误场景是否已说明？
- 是否存在错别字、格式错误、失效引用？
- 失败模式和错误处理是否描述清楚？
- 是否存在应明确写出的隐性假设？
### 5. 逻辑谬误
检查推理错误：
- 循环论证："X 是对的，因为 X 这么说"
- 虚假二分：只给出两种选择但实际存在更多
- 相关与因果混淆：把相关性当成因果
- 以偏概全：从个别案例推广到一般结论
- 预设前提：把未经证实的假设当作论证前提
### 6. AI 决策审查
审查 `implementation-notes.md`（如存在）中 AI 自行记录的决策：
- **Design Decisions**：记录的设计决策是否与最终代码一致？是否有代码中已做但未记录的决策？
- **Deviations**：记录的偏离是否确实发生？偏离理由是否成立？是否存在未记录的偏离？
- **Tradeoffs**：记录的取舍是否与最终实现吻合？是否遗漏了重要的替代方案考量？
- **Open Questions**：是否全部已解答？未解答的问题是否会影响代码正确性？
- **产出**：审查中发现的未记录决策、遗漏取舍、新发现的偏离 → **必须写入 `implementation-notes.md`**（按 ddev-exec 的四维度格式追加），不只是标记问题
## 判定标准
**只标记会误导读者、引发实现错误或阻碍理解的问题。** 措辞偏好和风格瑕疵不算问题。
但文档与代码事实矛盾**永远是阻塞级问题**。
## 输出格式
## 文档审查报告
**审查文档：** [列表]
**关联代码改动：** [摘要]
**问题清单：**
| # | 严重度 | 位置 | 问题描述 | 建议修复 |
|---|--------|------|---------|---------|
**未记录决策（需写入 implementation-notes.md）：**
| # | 类别 | 内容 | 建议写入维度 |
|---|------|------|-------------|
| | Design Decision / Deviation / Tradeoff / Open Question | 具体描述 | — |
> 即使本轮未发现新的未记录决策，也必须输出"本轮无新增"。
严重度定义：
- **阻塞**：文档与代码事实矛盾，会误导读者或引发实现错误
- **重要**：描述不准确、关键信息遗漏、前后矛盾
- **建议**：措辞优化、格式修正、补充说明
**审查结论：** 通过 / 需要修改
- 通过：阻塞 = 0 且重要 < 3
- 需要修改：阻塞 > 0 或重要 ≥ 3
若结论为"需要修改"，须逐项列出必须修复的内容。
审查报告应包含：
文档审查报告
============
审查文档：[文档路径列表]
关联代码改动：[改动范围描述]
问题清单：
- [严重度] 文件:区域 — 问题描述 → 建议修复
未记录决策：
- [Design Decision/Deviation/Tradeoff/Open Question] 描述 → 建议写入位置
严重度定义：
- 阻塞：文档与代码事实矛盾，会误导读者或引发实现错误
- 重要：描述不准确、关键信息遗漏、前后矛盾
- 建议：措辞优化、格式改进、补充说明
审查结论：[通过 / 有条件通过 / 需要修改]
修复后重新派发子代理审查时，必须遵守以下规则：
implementation-notes.md，不只在首轮写implementation-notes.md 的写入仅限于补充遗漏的决策、取舍和偏离，不得修改或推翻 spec/detail/plan 中已确定的大体路径、架构决策和核心设计。审查发现的问题修复也必须服从上游文档的既定方向