---
name: diff-verdict
description: 对代码改动进行结构化代码审查：分析 diff 的正确性、安全性、性能与可维护性，按严重度输出结论与逐条意见。当用户要求审查 PR、review 代码、检查 diff 或提交时使用。Reviews code changes and diffs with structured findings.
whenToUse: 用户要求「审查这个 PR/改动」「帮我看下这段 diff」「提交前检查」；或合入前需要一份独立审查意见时。
metadata:
  author: docgen
  version: "1.0.0"
  family: docgen
license: MIT
compatibility: 纯提示词技能，无需网络与第三方依赖；需要读取 diff、变更文件及其调用上下文的能力。
---

# diff-verdict：代码审查

## 职责

对一次代码改动给出可执行的审查意见（verdict）：结论明确、问题按严重度分级、每条意见都有文件与行号、同时指出亮点。本技能的核心原则是**只对 diff 负责**：意见必须锚定在本次改动的代码上，不扩大到与本次改动无关的历史问题。

## 何时使用

- 用户要求审查 PR / 合并请求 / 提交 / 未提交的 diff；
- 合入前自查：用户希望找出自己改动的盲点；
- 需要对外输出一份结构化审查意见（含结论与阻塞项）。

## 输入收集

| 证据 | 获取方式 | 用途 |
|---|---|---|
| 改动本身 | `git diff`、`git diff --stat`、PR 的 changed files | 审查主体 |
| 改动意图 | PR 描述、提交信息、分支名 | 判断「是否符合意图」 |
| 上下文 | 被调用/调用的相邻代码、公共函数定义 | 判断调用链影响 |
| 相关测试 | diff 中的测试改动、相邻测试文件 | 覆盖度判断 |
| 项目规范 | 已有 lint 配置、测试约定、文档 | 一致性判断 |

## 工作流程

1. **建立基线**：读 `--stat` 与提交信息，明确改动意图与规模，判断审查深度。
2. **逐文件审查**：按严重度扫描六类问题：
   - **正确性**：逻辑错误、边界条件、空值/异常路径、状态未更新、并发竞态；
   - **安全性**：注入、密钥/敏感信息、越权、不安全的默认值；
   - **性能**：无界循环、N+1 查询、不必要的重复计算、大对象常驻；
   - **可维护性**：死代码、命名误导、重复实现、复杂度爆炸、注释与代码不符；
   - **测试覆盖**：新逻辑缺少对应测试、测试只测 happy path、断言过弱；
   - **兼容性**：接口签名变化、数据格式/迁移、对调用方的影响。
3. **分级**：每条意见定级——**阻断**（必须改才能合入）/ **严重**（强烈建议改）/ **一般**（应当考虑）/ **建议**（可选优化）。
4. **核实**：对每条「疑似问题」再看一眼上下文，排除误报；无法确定的写「疑似」并说明验证方法。
5. **成稿**：结论 + 问题清单 + 亮点 + 验证建议，按下方模板输出。

## 输出模板与变量

```markdown
## 审查结论

**结论：{verdict}**

{overview}

### 问题清单

#### 阻断
{blockers}
#### 严重
{majors}
#### 一般
{minors}
#### 建议
{nits}

### 亮点
{good_parts}

### 验证建议
{verification}
```

| 模板变量 | 含义 | 示例 |
|---|---|---|
| {verdict} | 三选一：**批准**（无阻断/严重问题）/ **有条件批准**（有严重问题但可改后合入）/ **打回**（存在阻断问题） | 有条件批准 |
| {overview} | 2-4 句总评：改动规模、类型、总体质量、主要风险 | 新增技能解析逻辑，整体结构清晰，但存在一个边界输入可能导致崩溃 |
| {blockers} | 阻断问题列表，每条：`文件:行` + 问题 + 理由 + 建议 | `skills/x.py:42`：输入为空时 `cfg["x"]` 抛 KeyError，需先判空 |
| {majors} | 严重问题列表（同上格式） | … |
| {minors} | 一般问题列表（同上格式） | … |
| {nits} | 可选优化：命名、注释、格式 | … |
| {good_parts} | 亮点：设计好、测试到位、文档同步的地方（至少一条） | 新逻辑配套了边界用例测试，值得肯定 |
| {verification} | 验证建议：建议补充的测试、手动验证步骤、可运行的命令 | 建议增加空输入与超长输入两个用例 |

问题条目统一格式：`文件路径:行号` — 问题描述。**理由**：为什么是问题。**建议**：怎么改。

## 风格选项

默认语言跟随用户提问语言。用户可用自然语言覆盖：

- 语言：`语言=简体中文`、`language=en`
- 深度：`深度=快速`（只报阻断/严重，适合大 diff）、`深度=标准`（默认）、`深度=深入`（含逐文件细节与修改示例代码）
- 关注点：`关注=安全` / `关注=性能` / `关注=正确性`（只扫描指定类别）
- 语气：`语气=技术`（默认）、`语气=温和`（减少否定句式）

## 质量检查清单

输出前逐项自检：

- [ ] 每条问题都能定位到具体文件与行号
- [ ] 严重度分级合理：阻断 = 不修会出错/有安全风险，不是「风格不合我意」
- [ ] 每条建议可执行（给出改法或至少给出方向），不是空泛的「请改进」
- [ ] 没有把「与本次改动无关的历史问题」列为阻断
- [ ] 结论与问题清单一致：存在阻断却写「批准」即为自相矛盾
- [ ] 亮点至少一条——纯批评的审查不可信
- [ ] 「疑似」类问题明确标注并给出验证方法，未证实的猜测不当结论写
- [ ] 生成的代码/生成物文件（如 lockfile、构建产物）不逐行审查

## 不要做

- 不要把整个文件重写进意见里——只评论 diff 引入的问题
- 不要用「应该用 XX 模式」这类教条式意见，除非当前写法产生了实际风险
- 不要凭格式偏好升级严重度（缩进、命名风格属于建议级，除非有 lint 规则）
- 不要漏掉删除/重命名对调用方的影响——审查不只盯新增代码
- 不要替用户做合入决定之外的事情：给出结论和建议，合入与否由用户定

## 边界情况

- **无测试的仓库**：测试覆盖项降级为「建议」，并说明仓库现状，不强行要求补全套测试。
- **生成文件 / 第三方代码混入 diff**：跳过其内部细节，只提示「生成文件已变更，请确认来源」。
- **超大 diff**：先按 `--stat` 挑高风险文件（入口、数据层、并发、安全相关），快速深度只覆盖它们。
- **用户只给了一段代码**：没有 diff 上下文时，按「静态审查」处理并注明「未获得变更上下文，未检查调用链」。
- **前后意见矛盾**：重读相关代码，以最新状态为准，撤销过时意见。