Back to Details

diff-walkthrough

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diff Walkthrough

Diff 导读

Generate a grounded, reader-friendly walkthrough of a code change. Explain the change in the order a human should read it, not in filesystem or diff order.
Use the references for detailed rules when the diff is non-trivial:
  • references/file-roles.md
     for classifying changed files
  • references/reading-order.md
     for motif-based ordering
  • references/annotations.md
     for inline callouts and concerns
  • references/output-formats.md
     for HTML, Markdown, terminal, and JSON output contracts
生成一份有依据、对读者友好的代码变更讲解。按照人类应当阅读的顺序解释变更，而不是按照文件系统或 diff 的显示顺序。
当 diff 不简单时，使用以下 references 中的详细规则：
  • references/file-roles.md
    ：用于分类变更文件
  • references/reading-order.md
    ：用于基于变更主旨确定阅读顺序
  • references/annotations.md
    ：用于行内提示和注意事项
  • references/output-formats.md
    ：用于 HTML、Markdown、terminal 和 JSON 输出约定

Invocation

调用方式

Trigger on requests like:
User saysBehavior
"walk me through this diff"Explain the current unstaged or provided diff
"explain my staged changes"Use 
git diff --staged
"summarize this PR/MR"Fetch the hosted review with available tools, then explain it
"walk through HEAD~3..HEAD"Use the requested commit range
"review this diff"Include concerns and risks, not just narration
If the source is ambiguous, prefer the safest local source in this order: explicitly provided URL/range, staged diff, unstaged diff. Ask one short question only if multiple real sources exist and choosing one would materially change the answer.
当出现以下类型的请求时触发：
用户说法行为
“带我讲解这个 diff”解释当前未暂存的或已提供的 diff
“解释我的 staged changes”使用 
git diff --staged
“总结这个 PR/MR”使用可用工具获取托管评审，然后进行讲解
“带我讲解 HEAD~3..HEAD”使用指定的 commit range
“评审这个 diff”除叙述外，还包含注意事项和风险
如果来源不明确，按以下顺序优先选择最安全的来源：显式提供的 URL/range、staged diff、unstaged diff。只有在存在多个真实来源，且选择不同来源会实质改变答案时，才提出一个简短问题。

Options

选项

Parse options from the user's prompt. If omitted, use 
depth=standard
, 
format=html
, 
concerns=off
, and 
coverage=collapsed
.
OptionValuesMeaning
depth
skim
, 
standard
, 
deep
, 
teaching
Controls detail and vocabulary
format
html
, 
markdown
, 
terminal
, 
json
Controls output format
concerns
off
, 
on
Adds review-style risks only when requested or implied by "review"
coverage
collapsed
, 
full
Collapses noisy files by default; shows everything in full mode
Depth behavior:
DepthUse WhenOutput
skim
"quick", "brief", "tldr"Intent, impact, reading order, major files only
standard
DefaultNarrative per meaningful file/group with representative hunks
deep
"deep", "thorough", "detailed"Cross-file relationships, edge cases, tests, migrations, risks
teaching
"novice", "teach me", "explain simply"Plain language, diagrams, definitions, why each layer matters
Format behavior:
FormatOutput
html
Write or serve a standalone walkthrough artifact and return how to view it
markdown
Return or write Markdown, using Mermaid diagrams when useful
terminal
Return a concise plain-text walkthrough with ASCII diagrams/tables
json
Return structured data for another tool to render
If the user asks for a path, write there. Otherwise write generated walkthrough artifacts under 
/tmp
using 
mktemp
; do not place default generated walkthrough files in the repository workspace.
从用户提示中解析选项。如果省略，则使用 
depth=standard
、
format=html
、
concerns=off
和 
coverage=collapsed
。
选项值含义
depth
skim
、
standard
、
deep
、
teaching
控制讲解细节和术语使用方式
format
html
、
markdown
、
terminal
、
json
控制输出格式
concerns
off
、
on
仅在用户明确请求或通过“评审”暗示需要时，添加评审式风险说明
coverage
collapsed
、
full
默认折叠噪声文件；完整模式显示所有内容
不同深度的行为：
深度使用场景输出
skim
“quick”、“brief”、“tldr”变更意图、影响、阅读顺序和主要文件
standard
默认按有意义的文件或文件组进行叙述，并提供代表性 hunks
deep
“deep”、“thorough”、“detailed”跨文件关系、边界情况、测试、迁移和风险
teaching
“novice”、“teach me”、“explain simply”使用通俗语言、图表、定义，并解释每一层为何重要
不同格式的行为：
格式输出
html
编写或提供独立的 walkthrough 产物，并返回查看方式
markdown
返回或写入 Markdown，并在适合时使用 Mermaid 图表
terminal
返回带有 ASCII 图表或表格的简洁纯文本 walkthrough
json
返回供其他工具渲染的结构化数据
如果用户指定路径，则写入该路径。否则，使用 
mktemp
将生成的 walkthrough 产物放在 
/tmp
下；不要将默认生成的 walkthrough 文件放入 repository workspace。

Source Fetching

来源获取

Use the most specific available tool for the source:
  1. Local git: use 
    git diff
    , 
    git diff --staged
    , 
    git show
    , or 
    git diff <range>
    .
  2. Hosted review URL: use the matching MCP first when available; only fall back to the matching CLI such as 
    gh
    or 
    glab
    when no suitable MCP is available, then use a local clone if present.
  3. Pasted diff: parse the provided unified diff directly.
  4. Patch files: read the file and treat it as the source diff.
Collect enough context to explain the change accurately:
  • Unified diff per changed file
  • File list and line stats
  • Commit messages when available
  • Hosted review title, description, author, and target/source refs when available
  • Nearby source context only when the diff alone is insufficient
Do not assume vendor-specific infrastructure. This skill must work without hosted-review integrations or Plannotator.
使用可用的最具体工具获取来源：
  1. Local git：使用 
    git diff
    、
    git diff --staged
    、
    git show
    或 
    git diff <range>
    。
  2. Hosted review URL：在有可用工具时，优先使用对应的 MCP；仅当没有合适的 MCP 时，才回退到 
    gh
    或 
    glab
    等对应 CLI；如果存在本地 clone，也可使用。
  3. Pasted diff：直接解析提供的 unified diff。
  4. Patch files：读取文件，并将该文件视为来源 diff。
收集足够的上下文，以便准确解释变更：
  • 每个变更文件的 unified diff
  • 文件列表和行数统计
  • 可用时的 commit messages
  • 可用时的 hosted review 标题、描述、作者以及 target/source refs
  • 仅在 diff 本身不足以解释内容时获取附近的源代码上下文
不要假设存在特定厂商的基础设施。该 skill 必须能够在没有 hosted-review 集成或 Plannotator 的情况下工作。

Plannotator

Plannotator

Before producing HTML, check whether Plannotator is available with a lightweight probe such as 
command -v plannotator
and, if needed, inspect its help output. Also check obvious repo scripts only if the repository already references Plannotator.
Use Plannotator when all are true:
  • The requested format is 
    html
    .
  • Plannotator is installed or clearly available through the repo tooling.
  • Its interface can render the prepared walkthrough without guessing unsupported flags.
When Plannotator is available and suitable, write the prepared walkthrough as Markdown under 
/tmp
using 
mktemp
, then open that Markdown file with 
plannotator annotate <file.md> --gate
when the installed help shows 
--gate
is supported. Return the Markdown path and the Plannotator command used.
If Plannotator returns reviewer comments from the annotation gate, handle them based on the source. For local sources that can be safely edited, treat comments as user feedback on the current changes: inspect the referenced code or docs, make the requested fixes when they are safe and clear, run the smallest relevant validation, then generate a new walkthrough artifact under 
/tmp
and open it with Plannotator again. For remote reviews or other sources the agent cannot safely modify, do not attempt fixes; instead respond with an analysis of whether each comment is valid, grounded, in scope for the review, and what change would address it. If the feedback is ambiguous, destructive, or outside the requested diff, ask one short clarifying question before editing or recommending action. Continue the local-fix loop until the gate is approved, comments are exhausted, or the user stops the flow.
If Plannotator is missing, unsuitable, or its interface is unclear, generate a standalone HTML file under 
/tmp
using 
mktemp
, then open or serve it with a lightweight local viewer such as 
python3 -m http.server <port> --directory <dir>
. Return the HTML path, server URL, and any command needed to stop the server. Do not make Plannotator a hard dependency.
Mention in the final response whether Plannotator was used or whether the direct HTML fallback was used.
生成 HTML 前，先使用轻量探测方式检查 Plannotator 是否可用，例如运行 
command -v plannotator
，必要时查看其帮助输出。只有当 repository 已经引用 Plannotator 时，才检查明显的 repo scripts。
仅当以下条件全部成立时使用 Plannotator：
  • 请求的格式为 
    html
    。
  • Plannotator 已安装，或可通过 repo tooling 明确获得。
  • 其接口能够在不猜测不支持的参数的情况下渲染准备好的 walkthrough。
当 Plannotator 可用且适合使用时，使用 
mktemp
将准备好的 walkthrough 以 Markdown 形式放在 
/tmp
下；当已安装版本的帮助信息表明支持 
--gate
时，使用 
plannotator annotate <file.md> --gate
打开该 Markdown 文件。返回 Markdown 路径和所用的 Plannotator 命令。
如果 Plannotator 的 annotation gate 返回了评审意见，应根据来源处理。对于可以安全编辑的本地来源，将这些意见视为用户对当前变更的反馈：检查所引用的代码或文档，在修改安全且明确时完成所请求的修复，运行最小范围的相关验证，然后在 
/tmp
下生成新的 walkthrough 产物，并再次使用 Plannotator 打开。对于远程评审或其他 Agent 无法安全修改的来源，不要尝试直接修复；应改为分析每条意见是否有效、是否有依据、是否属于本次评审范围，以及应进行何种修改才能解决。如果反馈含义不清、可能造成破坏或超出所请求的 diff 范围，则在编辑或提出修改建议前只提出一个简短问题。继续本地修复循环，直到 gate 获批、意见处理完毕或用户要求停止。
如果 Plannotator 缺失、不适合使用或其接口不明确，则使用 
mktemp
在 
/tmp
下生成独立 HTML 文件，然后使用轻量级本地 viewer 打开或提供该文件，例如 
python3 -m http.server <port> --directory <dir>
。返回 HTML 路径、服务器 URL，以及停止服务器所需的命令。不要将 Plannotator 设为硬依赖。
在最终响应中说明使用了 Plannotator，还是使用了直接 HTML fallback。

Workflow

工作流

1. Read The Whole Change

1. 阅读完整项变更

First identify the motif before narrating files:
  • What is the one-sentence purpose of the change?
  • Is it a feature, bugfix, refactor, revert, migration, dependency update, or mechanical change?
  • Which files are the conceptual foundation, core behavior, wiring, UI, tests, docs, or noise?
  • What has to be understood before the rest makes sense?
Do not summarize each file independently until you understand the cross-file story.
开始逐个叙述文件之前，先识别变更的主旨：
  • 这项变更的一句话目的是什么？
  • 它属于 feature、bugfix、refactor、revert、migration、dependency update，还是 mechanical change？
  • 哪些文件承担概念基础、核心行为、连接集成、UI、测试、文档或噪声职责？
  • 在理解其余内容之前，必须先理解什么？
在理解跨文件的整体变更逻辑之前，不要分别总结每个文件。

2. Classify Files

2. 对文件进行分类

Classify each file as 
foundation
, 
core
, 
wiring
, 
ui
, 
test
, 
docs
, or 
noise
; classify its change as 
new
, 
mod
, 
del
, or 
ren
. Collapse 
noise
by default. In 
coverage=full
, include every file but still label noisy files clearly. For detailed rules, follow 
references/file-roles.md
.
将每个文件分类为 
foundation
、
core
、
wiring
、
ui
、
test
、
docs
或 
noise
；将其变更分类为 
new
、
mod
、
del
或 
ren
。默认折叠 
noise
。在 
coverage=full
下包含每个文件，但仍需清楚标注噪声文件。详细规则参见 
references/file-roles.md
。

3. Choose Reading Order

3. 选择阅读顺序

Use this default order unless the motif calls for an override: foundation, core behavior, wiring and integration, UI, tests, docs, then noise.
Overrides:
  • Bugfix: start with the failing behavior or fix, then proof/tests, then supporting context.
  • Revert: explain what is being backed out and why; avoid over-narrating restored code.
  • Mechanical change: group files by repeated pattern and show one representative example.
  • Migration: start with the old-to-new model, then compatibility or data handling, then call sites.
For mixed or mechanical diffs, follow 
references/reading-order.md
.
除非变更主旨要求采用其他顺序，否则默认依次为：foundation、core behavior、wiring and integration、UI、tests、docs，最后是 noise。
覆盖规则：
  • Bugfix：先说明失败行为或修复方式，然后说明证据与测试，最后补充相关上下文。
  • Revert：说明正在撤销的内容及其原因；避免过度叙述被恢复的代码。
  • Mechanical change：按重复模式对文件分组，并展示一个代表性示例。
  • Migration：先说明从旧模型到新模型的变化，然后说明兼容性或数据处理，最后说明调用位置。
对于混合型或 mechanical diff，请遵循 
references/reading-order.md
。

4. Explain With Diagrams

4. 使用图表解释

Prefer diagrams or charts when they clarify relationships. Do not add decorative diagrams that repeat prose.
Useful diagram types:
  • Reading-order map: foundation -> core -> wiring -> tests
  • Request/data flow: input -> transformation -> storage/output
  • Review feedback loop: walkthrough -> Plannotator comments -> fixes -> refreshed walkthrough
  • Code ownership or responsibility flow: caller -> adapter -> core logic -> output
  • Before/after table for API or behavior changes
  • Risk matrix when 
    concerns=on
  • File-role chart for large diffs
Prefer flow diagrams when they reveal sequence, responsibility, or feedback loops that prose would force the reader to reconstruct. Avoid decorative diagrams that restate the same bullet list. For HTML, use simple inline SVG, CSS boxes, or tables so the output opens without a build step. For Markdown, use Mermaid when appropriate and include a plain table fallback if the diagram is essential. For terminal output, use ASCII arrows and compact tables.
当图表能够清晰说明关系时，优先使用图表或示意图。不要添加只是重复文字内容的装饰性图表。
适用的图表类型：
  • 阅读顺序图：foundation -> core -> wiring -> tests
  • 请求或数据流：input -> transformation -> storage/output
  • 评审反馈循环：walkthrough -> Plannotator comments -> fixes -> refreshed walkthrough
  • 代码所有权或职责流：caller -> adapter -> core logic -> output
  • API 或行为变化的前后对照表
  • concerns=on
    时的风险矩阵
  • 大型 diff 的文件角色图
当流程图能够展示顺序、职责或反馈循环，而文字会迫使读者自行重建这些关系时，优先使用流程图。不要使用只是重复项目符号列表的装饰性图表。对于 HTML，使用简单的内联 SVG、CSS 方框或表格，使输出无需构建步骤即可打开。对于 Markdown，在适合时使用 Mermaid；如果图表不可或缺，同时提供普通表格作为 fallback。对于 terminal 输出，使用 ASCII 箭头和紧凑表格。

5. Write The Walkthrough

5. 编写 Walkthrough

For each meaningful file or group:
  • State what changed concretely, naming symbols, functions, endpoints, commands, or types from the diff.
  • Explain how it relates to earlier and later files in the reading order.
  • Include representative hunks or short code snippets when they teach the change better than prose, especially for new contracts, changed control flow, boundary validation, API shape changes, or subtle removals. Keep snippets small and omit unrelated context.
  • Call out subtle behavior changes separately from obvious edits.
  • In 
    teaching
    depth, define jargon before using it heavily.
  • In 
    deep
    depth, cover edge cases, compatibility, tests, and operational impact.
When 
concerns=on
, add a clearly separate concerns section. Only include concerns grounded in the diff or inspected context. Do not invent risks.
For line-level annotations, use the categories and anti-hallucination rules in 
references/annotations.md
.
对于每个有意义的文件或文件组：
  • 具体说明发生了什么变化，并点明 diff 中的 symbols、functions、endpoints、commands 或 types。
  • 解释它与阅读顺序中前后文件的关系。
  • 当代表性 hunks 或简短代码片段比文字更有助于理解变更时，将其包含在内，尤其是涉及新 contracts、控制流变化、边界校验、API 形态变化或细微删除时。保持片段简短，并省略无关上下文。
  • 将细微的行为变化与显而易见的修改分开说明。
  • 在 
    teaching
    深度下，大量使用专业术语前先给出定义。
  • 在 
    deep
    深度下，涵盖边界情况、兼容性、测试和运维影响。
当 
concerns=on
时，添加一个明确独立的注意事项部分。只包含基于 diff 或已检查上下文得出的注意事项，不要虚构风险。
对于行级标注，请使用 
references/annotations.md
 中的分类和反幻觉规则。

6. Produce The Chosen Format

6. 生成所选格式

HTML should include:
  • Title, source metadata, and generated timestamp
  • Executive summary
  • File-role chart or reading-order diagram when useful
  • Guided walkthrough in reading order
  • Representative diff hunks or code snippets
  • Tests and confidence section
  • Concerns section only when enabled
Markdown should mirror the same structure. Terminal output should be shorter and avoid large hunks. JSON should include at least 
summary
, 
source
, 
options
, 
files
, 
readingOrder
, 
diagrams
, 
sections
, 
tests
, and 
concerns
.
Use 
references/output-formats.md
 as the output contract for larger walkthroughs or when another tool will consume the result.
HTML 应包含：
  • 标题、来源元数据和生成时间戳
  • 执行摘要
  • 有用的文件角色图或阅读顺序图
  • 按阅读顺序组织的引导式讲解
  • 代表性 diff hunks 或代码片段
  • 测试与置信度部分
  • 仅在启用时包含注意事项部分
Markdown 应镜像相同结构。Terminal 输出应更简洁，并避免大型 hunks。JSON 至少应包含 
summary
、
source
、
options
、
files
、
readingOrder
、
diagrams
、
sections
、
tests
和 
concerns
。
对于大型 walkthrough，或结果将由其他工具消费时，使用 
references/output-formats.md
 作为输出约定。

Rules

规则

  • Ground every claim in the diff, commit metadata, or inspected source context.
  • Prefer explanation over review unless the user asks for review or 
    concerns=on
    .
  • Do not paste entire large diffs; choose representative hunks.
  • Do not fabricate line numbers, file paths, symbols, or intent.
  • Keep generated files local to the workspace or requested output path.
  • If verification is feasible, run the smallest relevant check for changed generated assets or scripts.
  • If the diff is too large to fully process, say what was covered and what was collapsed.
  • 每项结论都必须以 diff、commit metadata 或检查过的源代码上下文为依据。
  • 除非用户要求评审或设置 
    concerns=on
    ，否则优先进行解释而非评审。
  • 不要粘贴完整的大型 diff；应选择代表性 hunks。
  • 不要虚构行号、文件路径、symbols 或变更意图。
  • 将生成文件保留在工作区或用户指定的输出路径中。
  • 如果可以验证，针对变更后的生成资源或 scripts 运行最小范围的检查。
  • 如果 diff 太大而无法完整处理，请说明已覆盖的内容以及已折叠的内容。