القائمة
文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 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 中已确定的大体路径、架构决策和核心设计。审查发现的问题修复也必须服从上游文档的既定方向