explain-diff-for-human-review

让代码差异适合人类检视

把原始 diff 转化为 reviewer 能快速理解、逐层核验并作出决定的材料。报告不是 diff 的自然语言复述，也不替人自动批准代码。

目标

报告应同时满足两种阅读深度：

• reviewer 在第一屏内理解修改目的、可观察行为变化、最高风险、待确认决定和验证状态；
• reviewer 可以沿证据链接继续检查相关文件、符号、调用方、测试和原始 diff。

报告深度应与改动风险和复杂度相称。小改动不要强行生成完整架构分析；大改动不要用一句摘要掩盖跨模块影响。

确定范围与证据

1. 准确解析用户指定的目标：单个提交、提交范围、分支比较、PR/MR、暂存区、工作区或指定文件。
2. 如果目标不明确，使用对话中最近讨论的一组改动，并在报告中标明该假设。
3. 检查 diff、修改前的代码、相关调用方、测试、配置和文档。按需查看提交历史，理解难以从代码本身确认的原因。
4. 区分代码中可以确认的事实、提交或需求中声明的意图，以及检视者作出的推断。明确标注不确定结论。
5. 除非用户要求修复，否则只检视，不修改产品代码，也不改写 PR。

优先使用仓库原生命令，例如：

git show --stat --oneline <commit>
git diff <base>...<head>
git show <commit> -- <path>
rg "<symbol>" <relevant-paths>

先建立变更地图

在设计报告前，先回答五个问题：

1. 为什么要改？
2. 用户、调用方或运维会观察到什么不同？
3. 哪条运行时路径、数据流或职责边界发生了变化？
4. 最大风险和真正需要人决定的取舍是什么？
5. 现有验证证明了什么，还没有证明什么？

据此给出建议的 Review 顺序。按行为和因果链组织，不要按文件名逐个复述。

选择最小有效视图

视觉表达用于降低理解成本，不用于装饰。只保留回答当前 Review 问题所需的调用、文件、状态和边界。通常使用一到三个视图，不需要覆盖所有形式。

• 局部逻辑或算法：使用短小伪代码。
• 运行时调用关系：使用调用树。
• UI 结构与状态归属：使用组件树，并标出关键文件或模块。
• 文件职责或大范围重构：使用浅层文件树，每个目录只写一句职责。
• 组件交互、控制流或数据流：使用紧凑流程图；HTML 中优先使用带标签的 CSS 图示或内联 SVG。
• 已有形状中的局部变化：优先使用 diff 形式，在调用树、文件树、组件树或伪代码上直接标出增删。
• 大部分内容都是新的，或省略上下文会隐藏归属和顺序：展示一个完整但最短的目标结构。

每个视图紧邻它所解释的简短文字，并注明它是代码事实、根据代码简化的模型，还是建议方案。不要把概念图伪装成真实调用链。

生成自包含报告

除非用户指定其他位置，否则将 UTF-8 HTML5 文件写入本 Skill 目录下的 reports/explain-diff-<target>.html。运行时确定当前 Skill 所在目录；如果 reports 不存在则创建。不要假设固定安装路径。

报告必须可以直接打开：

• 内嵌全部 CSS，不使用远程字体、脚本、样式表、图片或分析服务；
• 使用语义化 HTML、响应式布局、清晰的键盘焦点和足够的文字对比度；
• 对代码、路径、提交信息和用户文本进行 HTML 转义；
• 使用 <details> 折叠长代码、原始 diff、验证命令和次要证据；
• 提供打印样式，确保导出 PDF 后仍然可读。

报告结构

只保留适用于本次改动的章节，不要为了模板完整而制造空内容。

第一屏：Review 摘要

显示仓库、检视范围、基准版本、改动规模，以及：

• 一句话说明为什么改、改了什么；
• 最小的“修改前 → 修改后”行为视图；
• 最高优先级风险；
• reviewer 必须确认的决定；
• 已执行验证的真实状态；
• 建议从哪里开始 Review。

风险等级使用：严重、高、中、低、提示。总体结论仅限：可以合入、可以合入但需要后续处理、需要修改。结论必须由证据支持，并明确最终决定属于人类 reviewer。

改动导览

按行为或职责组织改动。每组说明修改目的、关键实现选择、涉及的文件和符号、输入输出、状态、失败行为及兼容性影响。展示最小有效视图，原始细节放入折叠区域。

检视发现

将可执行发现按严重程度排序。每项包括：

• 严重程度和简短标题；
• 文件、符号和代码行证据；
• 可能的失败场景或需要确认的问题；
• 建议的处理决定或后续工作。