pr-review-canvas

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Review Canvas

PR审查画布

Build a canvas that presents a PR diff reorganized for reviewer comprehension — not in file-tree order.
构建一个重新组织PR差异的画布,以提升评审者的理解效率——而非按文件树顺序展示。

Prerequisites

前提条件

Read
~/.cursor/skills-cursor/canvas/SKILL.md
first. It contains the generation policy, design guidance, slop rules, self-check, and file-path conventions you must follow. The full component and hook surface is declared in
~/.cursor/skills-cursor/canvas/sdk/index.d.ts
and its sibling
.d.ts
files — read them to discover exact exports and prop shapes rather than guessing.
请先阅读
~/.cursor/skills-cursor/canvas/SKILL.md
。其中包含你必须遵循的生成规则、设计指南、容错规则、自检要求和文件路径约定。完整的组件与Hook接口声明在
~/.cursor/skills-cursor/canvas/sdk/index.d.ts
及其同级
.d.ts
文件中——请阅读这些文件以了解确切的导出内容和属性结构,而非猜测。

Gather the diff

收集差异

Expect a GitHub PR link (a full URL like
https://github.com/<owner>/<repo>/pull/<n>
, or an equivalent
gh
-resolvable reference). Use
gh pr diff <pr>
to collect every file's path, additions, deletions, and hunks.
If the user didn't provide a PR link, stop and ask. Do not guess at the current branch, infer from recent history, or fall back to a local
git diff
. Ask the user which diff they want to review — a specific PR URL or number — and wait for their reply before continuing.
预期用户提供GitHub PR链接(完整URL如
https://github.com/<owner>/<repo>/pull/<n>
,或可通过
gh
解析的等效引用)。使用
gh pr diff <pr>
命令收集每个文件的路径、新增内容、删除内容和代码块。
如果用户未提供PR链接,请停止操作并询问。 不要猜测当前分支、从近期历史推断,或退而求其次使用本地
git diff
。询问用户想要审查哪个差异——具体的PR URL或编号——等待用户回复后再继续。

Group changes for comprehension

按理解逻辑分组变更

Do not present files in alphabetical or tree order. Reorganize into sections ordered by reviewer value:
  1. Core logic — New behavior, algorithm changes, state transitions, API surface changes. Show full diffs with surrounding context.
  2. Wiring & integration — Route registration, dependency injection, config plumbing that connects the core logic. Condensed — enough to confirm correctness.
  3. Boilerplate & mechanical — Import reordering, renames, generated code, formatting, type re-exports. Summarize as a list of file names and stats. No inline diffs unless specifically relevant.
Lead with core logic. The reviewer's attention is freshest at the top.
请勿按字母顺序或树状顺序展示文件。按评审价值重新组织为以下部分,顺序如下:
  1. 核心逻辑 —— 新行为、算法变更、状态转换、API接口变更。展示包含上下文的完整差异。
  2. 连接与集成 —— 路由注册、依赖注入、连接核心逻辑的配置管道。精简展示——只需足够确认正确性即可。
  3. 样板与机械性变更 —— 导入重排序、重命名、生成代码、格式调整、类型重导出。以文件名和统计信息列表的形式汇总。除非特别相关,否则不展示内联差异。
优先展示核心逻辑。评审者的注意力在最顶部时最为集中。

Distill complex logic into pseudocode

将复杂逻辑提炼为伪代码

When a core change involves dense or intricate logic — deeply nested conditions, state machines, retry/backoff flows, multi-step transformations — add a short pseudocode summary next to the diff. The pseudocode should strip away language syntax, error handling, and boilerplate to expose the essential algorithm or control flow in a few lines. This lets the reviewer confirm intent before reading the real code.
Only do this when the actual diff is hard to scan. Straightforward changes don't need a pseudocode mirror.
当核心变更涉及密集或复杂的逻辑——深度嵌套的条件、状态机、重试/退避流程、多步转换——在差异旁添加简短的伪代码摘要。伪代码应剥离语言语法、错误处理和样板代码,用几行代码揭示核心算法或控制流。这让评审者在阅读真实代码前就能确认意图。
仅当实际差异难以扫描时才这样做。简单的变更不需要伪代码镜像。

Trace tricky logic on a concrete example

通过具体示例追踪复杂逻辑

Pseudocode shows the shape of the change; an example trace shows it executing. When a hunk changes behavior in a way that's hard to predict from reading it — reordered effects, new short-circuits, altered edge cases — pick a concrete input and walk it through both the old and new code paths side-by-side, highlighting the step where they diverge and what the observable outcome is. Keep the input small and realistic.
Use this for genuinely surprising behavior changes, not every core hunk.
伪代码展示变更的形态;示例追踪展示其执行过程。当代码块的行为变更难以通过阅读预测时——如效果重排序、新的短路逻辑、修改的边缘情况——选择一个具体输入,并排遍历旧代码路径和新代码路径,突出显示两者分歧的步骤以及可观察的结果。保持输入小而真实。
仅针对真正令人意外的行为变更使用此方法,而非每个核心代码块。

Call attention to tricky things

关注复杂点

When a hunk contains something surprising, risky, or easy to miss, visually separate it from the surrounding diff and pair it with a short tag (e.g. "Subtle", "Breaking", "Race condition", "Perf") and a one-sentence explanation so the reviewer sees the concern and the code together.
Reserve these callouts for genuinely tricky items — overuse destroys signal.
当代码块包含令人惊讶、有风险或容易被忽略的内容时,将其与周围的差异视觉分隔开,并搭配简短标签(如“微妙”、“破坏性”、“竞态条件”、“性能”)和一句解释,让评审者同时看到关注点和代码。
仅将这些标注用于真正复杂的内容——过度使用会削弱信号。

Tone and content

语气与内容

Write reviewer-facing commentary, not a changelog. Focus on:
  • Why something changed, not just what changed.
  • Interactions between files — e.g. "The new validator in
    core.ts
    is invoked by the route added in
    routes.ts
    ."
  • Anything the diff alone doesn't make obvious.
Keep commentary terse. One or two sentences per note.
撰写面向评审者的评论,而非变更日志。重点关注:
  • 为什么进行变更,而非仅仅变更了什么。
  • 文件之间的交互——例如:
    core.ts
    中的新验证器由
    routes.ts
    中添加的路由调用。
  • 仅通过差异无法明确的任何内容。
保持评论简洁。每条注释一到两句话。

Be creative

发挥创意

The sections above are a floor, not a ceiling. The goal is the fastest possible path for the reviewer to understand this specific change — so look at the diff in front of you and ask what representation would actually help. A tiny state diagram, a before/after call graph, a table of input→output pairs, a timeline of commits, a confidence annotation per file, a single large callout with everything else collapsed — whatever fits the change.
The canvas SDK has charts, tables, diff views, DAG layout, cards, stats, interactive state, and more. Reach for whichever components best serve the change at hand. A review of a refactor looks different from a review of a bug fix looks different from a review of a new feature — let the canvas reflect that.
以上部分是基础要求,而非上限。目标是让评审者以最快的速度理解特定变更——因此查看眼前的差异,思考哪种呈现方式真正有帮助。一个小型状态图、前后调用图对比、输入→输出对表格、提交时间线、每个文件的置信度标注、一个包含所有其他折叠内容的大型标注——任何适合该变更的形式均可。
Canvas SDK包含图表、表格、差异视图、DAG布局、卡片、统计信息、交互状态等。选择最适合当前变更的组件即可。重构的审查、bug修复的审查、新功能的审查各不相同——让画布反映这些差异。