interactive-diff-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Diff Review Skill

Git Diff 审查工具

Interactive hunk-by-hunk code review. Parse → Review → Verify → Report → Apply → Commit.

交互式逐代码块（hunk）代码审查流程：解析 → 审查 → 验证 → 生成报告 → 应用修改 → 提交代码。

Commands

命令

Parse

$ARGUMENTS

to determine the command and diff target:

Command	Usage	Description
`review`	`/interactive-diff-review [target]`	Default. Full interactive review: parse → review → report
`--verify`	`/interactive-diff-review --verify`	Check report exists, matches current diff, and all hunks passed
`--apply`	`/interactive-diff-review --apply`	Fix code based on rejected hunks' review suggestions
`--commit`	`/interactive-diff-review --commit`	Generate and execute git commit (requires `--verify` pass first)

Target is optional:

<commit>

<commit_a> <commit_b>

, or omit for auto-detect (staged → workspace).

Commands can be combined:

/interactive-diff-review --apply --commit

will apply fixes then commit if verify passes.

解析

$ARGUMENTS

以确定命令和diff目标：

命令	用法	描述
`review`	`/interactive-diff-review [target]`	默认命令。完整交互式审查流程：解析 → 审查 → 生成报告
`--verify`	`/interactive-diff-review --verify`	检查报告是否存在、是否匹配当前diff，以及所有代码块是否通过审查
`--apply`	`/interactive-diff-review --apply`	根据被拒绝代码块的审查建议修复代码
`--commit`	`/interactive-diff-review --commit`	生成并执行Git提交（需先通过 `--verify` 验证）

**目标（Target）**为可选参数：

<commit>

、

<commit_a> <commit_b>

，或留空自动检测（暂存区 → 工作区）。

命令可组合使用：

/interactive-diff-review --apply --commit

将先应用修改，若验证通过则提交代码。

Command Routing

命令路由

Parse
```
$ARGUMENTS
```
— extract command flags and remaining positional args (diff target).
If no command flag is present → default to
```
review
```
.
Route to the corresponding section below.

解析
```
$ARGUMENTS
```
— 提取命令标志和剩余位置参数（diff目标）。
若无命令标志 → 默认使用
```
review
```
命令。
路由至下方对应流程。

Workflow Checklist

工作流程检查清单

Copy this checklist and check off items as you complete them:

Diff Review Progress:
- [ ] Step 1: Resolve & Parse
  - [ ] 1.1 Run resolve_diff.py to get diff + language
  - [ ] 1.2 Verify no error, inform user of diff source + language
  - [ ] 1.3 Run parse_hunks.py to split into hunks
  - [ ] 1.4 Handle edge cases ⚠️ Load references/edge-cases.md
- [ ] Step 2: Interactive Review ⚠️ CORE LOOP
  - [ ] Load references/review-format.md
  - [ ] 2.1 Display hunk (index/total, file, type, diff body)
  - [ ] 2.2 Provide analysis (summary, impact, risks, suggestions)
  - [ ] 2.3 Collect decision via ask_user_input (Accept / Reject / Skip)
  - [ ] 2.4 If rejected, ask reason (open-ended text follow-up)
  - [ ] 2.5 Show running tally, advance to next hunk
  - [ ] 2.6 Repeat 2.1–2.5 until all hunks done
  - [ ] 2.7 Loop back for any skipped hunks
- [ ] Step 3: Coverage Verification ⚠️ REQUIRED
  - [ ] 3.1 Re-run resolve_diff.py + parse_hunks.py
  - [ ] 3.2 Compare new hunks against reviewed hunks (file + header + body)
  - [ ] 3.3 If new/changed hunks → review them (back to Step 2)
  - [ ] 3.4 Confirm full coverage before proceeding
- [ ] Step 4: Generate Report
  - [ ] Load references/report-template.md
  - [ ] 4.1 Build Markdown report (detected language, diff order)
  - [ ] 4.2 Save to /mnt/user-data/outputs/diff-review-report.md
  - [ ] 4.3 Present to user

复制此清单，完成一项勾选一项：

Diff审查进度：
- [ ] 步骤1：解析与处理
  - [ ] 1.1 运行resolve_diff.py获取diff及代码语言
  - [ ] 1.2 确认无错误，告知用户diff来源及检测到的语言
  - [ ] 1.3 运行parse_hunks.py将diff拆分为代码块
  - [ ] 1.4 处理边缘情况 ⚠️ 加载references/edge-cases.md
- [ ] 步骤2：交互式审查 ⚠️ 核心循环
  - [ ] 加载references/review-format.md
  - [ ] 2.1 展示代码块（序号/总数、文件、类型、diff内容）
  - [ ] 2.2 提供分析（摘要、影响、风险、建议）
  - [ ] 2.3 通过用户输入收集决策（接受 / 拒绝 / 跳过）
  - [ ] 2.4 若拒绝，询问拒绝原因（开放式文本输入）
  - [ ] 2.5 显示当前统计结果，进入下一个代码块
  - [ ] 2.6 重复2.1–2.5直至所有代码块处理完毕
  - [ ] 2.7 回头处理所有跳过的代码块
- [ ] 步骤3：覆盖验证 ⚠️ 必需步骤
  - [ ] 3.1 重新运行resolve_diff.py + parse_hunks.py
  - [ ] 3.2 对比新代码块与已审查代码块（文件 + 头部 + 内容）
  - [ ] 3.3 若发现新/变更代码块 → 审查这些代码块（返回步骤2）
  - [ ] 3.4 确认覆盖所有代码块后再继续
- [ ] 步骤4：生成报告
  - [ ] 加载references/report-template.md
  - [ ] 4.1 构建Markdown报告（检测到的语言、diff顺序）
  - [ ] 4.2 保存至/mnt/user-data/outputs/diff-review-report.md
  - [ ] 4.3 向用户展示报告

Step 1: Resolve & Parse

步骤1：解析与处理

1.1 Run resolver

1.1 运行解析脚本

bash

python scripts/resolve_diff.py                       # auto: staged → workspace
python scripts/resolve_diff.py <commit>              # single commit
python scripts/resolve_diff.py <commit_a> <commit_b> # commit range

Returns JSON:

{ source, ref, language, diff, error }

bash

python scripts/resolve_diff.py                       # 自动检测：暂存区 → 工作区
python scripts/resolve_diff.py <commit>              # 单个提交
python scripts/resolve_diff.py <commit_a> <commit_b> # 提交范围

返回JSON格式：

{ source, ref, language, diff, error }

1.2 Verify & inform

1.2 验证并告知用户

error

is non-null → report to user and stop. Otherwise tell the user which diff source was resolved and what language was detected.

若

error

不为空 → 向用户报告错误并终止流程。否则告知用户已解析的diff来源及检测到的代码语言。

1.3 Save diff & run parser

1.3 保存diff并运行解析器

Extract the

diff

field from Step 1.1's JSON output and write it to a temporary file, then parse:

bash

undefined

提取步骤1.1中JSON输出的

diff

字段，写入临时文件，然后解析：

bash

undefined

Write the diff field to a temp file (agent should use Write tool or shell redirect)

将diff字段写入临时文件（Agent应使用Write工具或Shell重定向）

e.g. write resolve output's .diff value to /tmp/diff.txt

例如：将解析输出的.diff值写入/tmp/diff.txt

python scripts/parse_hunks.py --file /tmp/diff.txt


Returns JSON: `{ total, hunks: [{ index, file, header, body, type, status, reason }] }`

python scripts/parse_hunks.py --file /tmp/diff.txt


返回JSON格式：`{ total, hunks: [{ index, file, header, body, type, status, reason }] }`

1.4 Edge cases

1.4 边缘情况处理

Load

references/edge-cases.md

and handle accordingly.

加载

references/edge-cases.md

并相应处理。

Step 2: Interactive Review

步骤2：交互式审查

Before starting this step, load

references/review-format.md

for display format, analysis fields, and decision collection details.

All UI text uses the detected language from Step 1. Technical terms remain in English.

Loop through each hunk: display → analyze → collect decision → show tally → next. After the first pass, loop back for any skipped hunks.

开始此步骤前，加载

references/review-format.md

以获取展示格式、分析字段及决策收集的详细要求。

所有UI文本使用步骤1中检测到的语言。技术术语保留英文。

循环处理每个代码块：展示 → 分析 → 收集决策 → 显示统计 → 下一个。第一轮处理完成后，回头处理所有跳过的代码块。

Step 3: Coverage Verification

步骤3：覆盖验证

Re-run
```
resolve_diff.py
```
+
```
parse_hunks.py
```
with same arguments as Step 1.
Compare new hunks against reviewed hunks by
```
file + header + body
```
.
New/changed hunks found → go back to Step 2 for those hunks only.
Confirm full coverage. Only proceed to Step 4 when all hunks are decided.

使用与步骤1相同的参数重新运行
```
resolve_diff.py
```
+
```
parse_hunks.py
```
以获取当前代码块。
通过
```
文件 + 头部 + 内容
```
对比新代码块与已审查代码块。
若发现新/变更代码块 → 审查这些代码块（返回步骤2）。
确认所有代码块都已审查后，再进入步骤4。

Step 4: Generate Report

步骤4：生成报告

Before starting this step, load

references/report-template.md

for the full template.

Build the report in the detected language (technical terms in English), ordered by original diff sequence. Save to

diff-review-report.md

in the project root and present to user.

开始此步骤前，加载

references/report-template.md

获取完整模板。

使用检测到的语言构建报告（技术术语保留英文），按原diff顺序排列。保存至项目根目录的

diff-review-report.md

并展示给用户。

Command:

--verify

命令：

--verify

Validates that the review is complete and current.

Check
```
diff-review-report.md
```
exists in project root. If not → error: "No report found. Run
```
review
```
first."
Re-run
```
resolve_diff.py
```
+
```
parse_hunks.py
```
with same target args to get current hunks.
Parse the report's Overview table to extract reviewed hunks (file + type + status).
Compare:
- Every current hunk has a matching entry in the report (by file path + hunk header + body hash).
- No extra entries in report that don't exist in current diff (stale entries).
Check that all hunks have status ✅ Accepted (no ❌ Rejected, no missing).
Output result:
- PASS: "Verification passed. All N hunks reviewed and accepted. Ready to commit."
- FAIL — unreviewed hunks: List the unmatched hunks.
- FAIL — rejected hunks: List the rejected hunks with their reasons.
- FAIL — stale report: Report doesn't match current diff. Suggest re-running
```
review
```
  .

验证审查是否完整且与当前diff一致。

检查项目根目录是否存在
```
diff-review-report.md
```
。若不存在 → 错误提示：“未找到审查报告，请先运行
```
review
```
命令。”
使用相同的目标参数重新运行
```
resolve_diff.py
```
+
```
parse_hunks.py
```
以获取当前代码块。
解析报告中的概览表格，提取已审查的代码块（文件 + 类型 + 状态）。
对比：
- 每个当前代码块在报告中都有对应的条目（通过文件路径 + 代码块头部 + 内容哈希匹配）。
- 报告中不存在当前diff中没有的过期条目。
检查所有代码块的状态是否为✅ 已接受（无❌ 已拒绝或未处理的代码块）。
输出结果：
- 通过：“验证通过。所有N个代码块已审查并被接受。可进行提交。”
- 失败 - 未审查代码块：列出不匹配的代码块。
- 失败 - 被拒绝代码块：列出被拒绝的代码块及其原因。
- 失败 - 报告过期：报告与当前diff不匹配。建议重新运行
```
review
```
  命令。

Command:

--apply

命令：

--apply

Fixes code based on review suggestions for rejected hunks.

Check
```
diff-review-report.md
```
exists. If not → error.
Parse the report to find all ❌ Rejected hunks and their rejection reasons + analysis suggestions.
For each rejected hunk (in diff order): a. Read the relevant file and locate the code region from the hunk. b. Based on the rejection reason and the review analysis, generate a fix. c. Apply the fix using Edit tool. d. Show the user what was changed and why.
After all fixes applied, inform the user:
- "Applied fixes for N rejected hunks. Run
```
--verify
```
  or re-run
```
review
```
  to confirm."

Note:

--apply

does NOT re-run the review. The user should run

review

again or

--verify

after applying.

根据被拒绝代码块的审查建议修复代码。

检查
```
diff-review-report.md
```
是否存在。若不存在 → 错误提示。
解析报告，找出所有❌ 被拒绝的代码块及其拒绝原因和分析建议。
按diff顺序处理每个被拒绝的代码块： a. 读取相关文件，定位代码块对应的代码区域。 b. 根据拒绝原因和审查分析生成修复方案。 c. 使用Edit工具应用修改。 d. 向用户展示修改内容及原因。
所有修复应用完成后，告知用户：
- “已为N个被拒绝代码块应用修复。请运行
```
--verify
```
  或重新运行
```
review
```
  命令确认。”

注意：

--apply

不会重新运行审查流程。用户应在应用修改后重新运行

review

或

--verify

命令。

Command:

--commit

命令：

--commit

Generates and executes a git commit. Requires verification to pass first.

Run the
```
--verify
```
flow internally (same as above).
If verify FAILS → stop and show the failure reason. Do not commit.
If verify PASSES: a. Parse the report to build a commit message:
- Subject line: summarize the changes (max 72 chars), in detected language.
- Body: list the key changes from the report overview (accepted hunks grouped by file). b. Show the proposed commit message to the user for confirmation. c. On user approval:
- ```
git add -A
```
  (or stage the specific files from the review).
- ```
git commit
```
  with the message. d. Show the commit result.

生成并执行Git提交。需先通过验证步骤。

内部运行
```
--verify
```
流程（与上述步骤相同）。
若验证失败 → 终止流程并显示失败原因，不执行提交。
若验证通过： a. 解析报告以构建提交信息：
- 主题行：总结变更内容（最多72字符），使用检测到的语言。
- 正文：列出报告概览中的关键变更（按文件分组已接受的代码块）。 b. 向用户展示拟提交的信息以确认。 c. 用户确认后：
- 执行
```
git add -A
```
  （或暂存审查涉及的特定文件）。
- 使用构建好的信息执行
```
git commit
```
  。 d. 向用户展示提交结果。

Parameter Reference

参数参考

Parameter	Type	Description
(none)	—	Default `review` command, auto-detect diff source
`<commit>`	string	Commit hash, short hash, tag, or ref
`<commit_a> <commit_b>`	string	Commit range
`--verify`	flag	Run verification check on existing report
`--apply`	flag	Apply fixes for rejected hunks
`--commit`	flag	Verify + generate git commit

参数	类型	描述
无	—	默认使用 `review` 命令，自动检测diff来源
`<commit>`	字符串	提交哈希、短哈希、标签或引用
`<commit_a> <commit_b>`	字符串	提交范围
`--verify`	标志	对现有报告运行验证检查
`--apply`	标志	应用被拒绝代码块的修复方案
`--commit`	标志	验证 + 生成Git提交

Language

语言处理

Detected from
```
git log --oneline -10
```
by
```
resolve_diff.py
```
.
All UI, analysis, and report use detected language; technical terms stay English.
Mixed-language commits → most frequent wins.
No history → fall back to user's conversation language.

通过
```
resolve_diff.py
```
分析
```
git log --oneline -10
```
的输出检测语言。
所有UI、分析内容和报告使用检测到的语言；技术术语保留英文。
混合语言提交 → 使用出现频率最高的语言。
无提交历史 → 回退使用用户对话的语言。

File Structure

文件结构

git-diff-review/
├── SKILL.md                          # This file — workflow orchestration
├── scripts/
│   ├── resolve_diff.py               # Diff source + language detection
│   └── parse_hunks.py                # Unified diff → structured hunks
└── references/
    ├── review-format.md              # Step 2: display, analysis, decisions
    ├── report-template.md            # Step 4: Markdown report template
    └── edge-cases.md                 # Step 1.4: edge case handling

git-diff-review/
├── SKILL.md                          # 本文件 — 工作流程编排
├── scripts/
│   ├── resolve_diff.py               # Diff来源 + 语言检测
│   └── parse_hunks.py                # 统一diff → 结构化代码块
└── references/
    ├── review-format.md              # 步骤2：展示格式、分析字段、决策收集细节
    ├── report-template.md            # 步骤4：Markdown报告模板
    └── edge-cases.md                 # 步骤1.4：边缘情况处理

interactive-diff-review

Original

Translation

Git Diff Review Skill

Git Diff 审查工具

Commands

命令

Command Routing

命令路由

Workflow Checklist

工作流程检查清单

Step 1: Resolve & Parse

步骤1：解析与处理

1.1 Run resolver

1.1 运行解析脚本

1.2 Verify & inform

1.2 验证并告知用户

1.3 Save diff & run parser

1.3 保存diff并运行解析器

Write the diff field to a temp file (agent should use Write tool or shell redirect)

将diff字段写入临时文件（Agent应使用Write工具或Shell重定向）

e.g. write resolve output's .diff value to /tmp/diff.txt

例如：将解析输出的.diff值写入/tmp/diff.txt

1.4 Edge cases

1.4 边缘情况处理

Step 2: Interactive Review

步骤2：交互式审查

Step 3: Coverage Verification

步骤3：覆盖验证

Step 4: Generate Report

步骤4：生成报告

Command: --verify

命令：--verify

Command: --apply

命令：--apply

Command: --commit

命令：--commit

Parameter Reference

参数参考

Language

语言处理

File Structure

文件结构

Command:
`--verify`

命令：
`--verify`

Command:
`--apply`

命令：
`--apply`

Command:
`--commit`

命令：
`--commit`