review-diff

技能：审查差异

目的

仅审查当前变更（git diff：暂存 + 未暂存，以及可选的未跟踪文件），涵盖 5 个维度：意图 / 影响、回归 / 正确性、破坏性变更 / 兼容性、副作用 / 幂等性、可观测性。生成仅针对范围的发现列表，供 orchestrate-code-review 的范围步骤汇总使用。

---

核心目标

主要目标：仅针对差异范围（包括未跟踪文件），生成涵盖 5 个维度的发现列表。

成功标准（必须全部满足）：

1. ✅ 仅限差异范围：只审查变更集；不进行仓库级 / 架构 / 安全 / 语言特定检查
2. ✅ 覆盖全部 5 个维度：意图 / 影响、回归 / 正确性、破坏性变更 / 兼容性、副作用 / 幂等性、可观测性
3. ✅ 格式符合要求：每条发现均包含位置 / 类别=scope / 严重性 / 标题 / 描述 / 建议，详见 specs/findings-list.md
4. ✅ 位置精确：每条发现均标明具体的 file:line 或 @@ 区块
5. ✅ 验证 Bug 修复：必须验证 Bug 修复差异中的修复是否正确，并指出任何遗留或未完全解决的问题

---

范围边界

本技能负责：

• 当前 git diff（暂存 + 未暂存）
• 变更集中的未跟踪文件（默认包括，按整个文件新增处理）
• 涵盖 5 个维度的分析：意图 / 影响、回归 / 正确性、破坏性变更 / 兼容性、副作用 / 幂等性、可观测性

本技能不负责：

• 仓库级或快照级审查 → review-codebase
• 完整的编排式审查 → orchestrate-code-review
• 架构 / 安全 / 性能 / 测试认知维度 → 对应的认知原子技能
• 语言 / 框架特定约定 → 对应的原子技能

交接点：生成发现列表后，将其交给 orchestrate-code-review 的范围步骤进行汇总，或交给 orchestrate-repair-loop 进入修复迭代。

---

使用场景

• 提交前 / PR 前检查：提交前快速查看变更引入了什么
• 作为 orchestrate-code-review 的范围步骤：使用本技能或 review-codebase，不可同时使用两者
• 聚焦审查：用户要求“只看变更”

---

行为

范围解析

• 分析内容：变更集中的文件——差异（暂存 + 未暂存）以及默认包含的未跟踪文件
• 未跟踪文件处理：调用方传入路径和完整内容；将其视为整个文件新增，应用相同的 5 维检查清单，并标注 file:line
• 不分析的内容：未更改或不属于变更集的文件

5 维检查清单

针对每个已更改文件，按以下维度生成发现：

1. 意图与影响：更改了什么以及原因；对调用方 / 数据 / 配置 / 部署的影响
2. 回归与正确性：是否引入了新 Bug 或遗漏边界情况；Bug 修复差异是否完整解决问题
3. 破坏性变更与兼容性：是否破坏 API / 数据 / 配置契约；向后兼容性；版本管理 / 弃用
4. 副作用与幂等性：非预期副作用、数据损坏、重复执行风险、幂等性问题
5. 可观测性：变更是否添加或修复了在生产环境中调试所需的日志、指标和错误消息

特殊情况

• Bug 修复差异：验证修复是否正确，并记录任何遗留或未完全解决的问题
• 仅格式或注释的差异：生成一条次要发现：“仅格式 / 注释变更，没有行为变化”；若注释与代码相矛盾，则生成一条带建议的发现

---

输入与输出

输入

• git diff：当前分支相对于 HEAD 的已暂存和未暂存更改
• 未跟踪文件（默认包含）：路径 + 完整内容

输出

• 问题列表：标准格式（location / category=scope / severity / title / description / suggestion）
• 每个问题都必须带有文件:行号或 @@ 区块引用
• 每个问题都必须带有可执行的建议（修复方向 + 具体位置）

---

限制

硬性边界

• 不要审查 diff 之外的文件
• 不要输出缺少文件:行号引用的问题
• 不要使用含糊的措辞（“可能有问题”这类既没有指出类型也没有给出方向的表述 → 删除）
• 不要进行安全 / 架构 / 语言 / 框架检查（仅限范围维度）

技能边界

此处不处理（由其他原子技能负责）：

• 仓库级 / 快照级审查 → review-codebase
• 全维度编排 → orchestrate-code-review
• 安全 → review-security
• 架构 → review-architecture
• 语言 / 框架 → 对应的原子技能

---

自检

• 仅审查了变更集（diff 以及包含的未跟踪文件）
• 覆盖了全部 5 个维度
• 每个问题都符合格式（包含全部 6 个字段）
• 每个问题都带有文件:行号或 @@ 区块引用
• 每个问题都带有可执行的建议
• 已验证 Bug 修复 diff 中的修复是否正确

---

示例

示例 1：API 更改

• 输入：添加查询参数并调整响应结构的 diff
• 预期：问题涵盖意图 / 影响（对调用方）、向后兼容风险，以及破坏性更改的建议（例如版本管理或弃用）；引用确切的行号或 @@ 区块；不涉及安全 / 架构问题（这些由对应的原子技能负责）

示例 2：Bug 修复

• 输入：修复空指针和错误码的 diff
• 预期：确认修复有效，并检查是否仍存在类似的空指针 / 错误码问题；覆盖可观测性维度（日志 / 错误）；引用更改的行；category=scope

示例 3：仅格式调整 / 注释

• 输入：仅包含缩进 / 空白 / 注释更改的 diff
• 预期：不输出问题，或输出一个轻微问题：“仅格式调整 / 注释，没有行为更改”；如果注释与代码矛盾，则输出问题并给出建议

示例 4：变更集中的新（未跟踪）文件

• 输入：diff 以及一个未跟踪文件（路径 + 完整内容）
• 预期：将新文件作为整个文件新增内容进行审查；应用 5 维度检查清单；location=带行号引用的路径；category=scope