walk-pr
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWalk the user through a PR or large diff one sub-changeset (SC) at a time — a group of files that makes sense together — and one review topic at a time within it.
Input = PR number, PR URL, diff range, or nothing (infer the current branch's PR; fall back to the diff against the repository's actual remote-tracking default branch).
Reader model. The reviewer lives in the repo but has zero context on this PR. Codebase vocabulary is shared ground; vocabulary the PR introduces is not — new types, modes, modules, domain terms need explicit introduction before downstream content uses them.
Attention contract. Every mode of this skill serves the same contract: high-level orientation first, one idea active at a time, and depth — rationale, code, diffs, long text — only when the reviewer asks for it. In chat that is the one-SC/one-topic discipline below; in canvas it is a visual map with everything textual behind taps. Whenever a presentation choice arises, the failure to avoid is the text wall: never put more in front of the reviewer than the current idea needs.
Open with orientation. Present a PR primer before the change overview: a one-paragraph problem statement in workflow vocabulary, plus — only when load-bearing — a concept glossary (workflow-level definitions, not type signatures), a component sketch, or a reading hint. Then a categorized overview (load-bearing vs scaffolding/data, biggest-signal-first); skip both on trivial diffs.
Per sub-changeset, depth on demand. The always-visible surface per SC is a one-sentence behavior summary (what changes for the user) and a one-sentence verification probe (how to observe it works). Everything else — boundary view, topics, diff — is depth the reviewer expands only on SCs that need it.
Inside the depth — boundary-first. Open with a boundary view brief enough to orient the reviewer before the diff, at module-boundary altitude — new/changed types, signatures at module edges, dependency-edge shifts, contract changes — load-bearing pieces only, no inventory. Diff hunks are per-file, on-demand evidence, not the default exposition. Then topics.
Topic shape. Surface review topics (probes, trade-offs, recommendations) one at a time. Frame each topic so the reviewer can make one call without opening the supporting material: name the concrete concern in codebase vocabulary, then the recommendation. No nested clauses, no embedded justification, no narrated reasoning. Put rationale, code excerpts, and alternatives in supporting material (a follow-up message or on-demand probe), not the headline. Wait for the user's response before advancing. Don't batch — "thoughts on all of these?" is the failure mode this skill prevents. Hold positions under pushback when evidence still supports them.
Triage, then post. Capture the user's response per topic. When the walk completes, triage every captured item — topic responses and free notes alike — into three kinds: settled calls that become draft comments; questions the reviewer raised that you must answer first — from the code, the repo's ADRs, and any design doc the PR implements (fetch it; design-vs-implementation deviations are prime review material) — because investigation routinely flips or reshapes the would-be comment; and drops that generate nothing. Then confirm the proposed comments with the reviewer one at a time — a batched approval table recreates the overload the walk exists to prevent — each line-anchored where it ties to a specific code location, file-level or PR-level otherwise. Once all items lock, post them as a single PR review using the available GitHub review mechanism. The walk ends once the review is posted.
--canvasreferences/CANVAS_MODE.md引导用户逐步了解一个 PR 或大型 diff,每次只处理一个子变更集(SC),并在其中每次只处理一个评审主题。
输入 = PR 编号、PR URL、diff 范围,或不提供任何输入(推断当前分支的 PR;回退到与仓库实际远程跟踪默认分支之间的 diff)。
读者模型。 评审者身处该代码库,但对这个 PR 没有任何背景信息。代码库既有术语是共同基础;PR 新引入的术语则不是——新类型、模式、模块和领域术语都必须在后续内容使用前明确介绍。
注意力约定。 此 skill 的每种模式都遵循同一约定:先提供高层定位,每次只激活一个想法,只有评审者主动要求时才展开深度内容。在聊天中,体现为下文“一次一个 SC/一个主题”的纪律;在 canvas 中,则体现为一张可视化地图,所有文字内容都需点击后查看。每当需要选择呈现方式时,必须避免的失败是“文字墙”:绝不能把超出当前想法所需的信息一次性呈现给评审者。
先定位再开始。 在介绍变更前,先给出一个 PR 导读:用一段话、以工作流术语描述问题;仅在确有必要时,附上概念术语表(工作流层面的定义,而非类型签名)、组件草图或阅读提示。然后给出分类概览(核心内容与脚手架/数据,优先呈现最重要的信息);对于琐碎的 diff,可省略这些内容。
每个子变更集的深度按需展开。 每个 SC 始终可见的内容包括一句话的行为摘要(用户侧会发生什么变化)和一句话的验证探针(如何观察它是否正常工作)。其余内容——边界视图、主题、diff——都属于深度内容,只在评审者需要时针对相应 SC 展开。
深入内容——先看边界。 先给出一个足以让评审者完成定位的边界视图,保持在模块边界层级——新增或变更的类型、模块边界的签名、依赖边的变化、契约变更——只呈现关键部分,不做清单罗列。Diff hunks 是按文件、按需提供的证据,而不是默认讲解内容。然后再展开主题。
主题的组织方式。 每次只呈现一个评审主题(探针、取舍和建议)。每个主题都应让评审者无需打开辅助材料便能做出一个判断:先用代码库术语指出具体问题,再给出建议。不要使用嵌套从句,不要嵌入论证理由,也不要叙述推理过程。将理由、代码片段和替代方案放入辅助材料(后续消息或按需探针),而不是放在主题标题中。等待用户回应后再继续。不要批量处理——“对这些主题有什么想法?”正是此 skill 要避免的失败模式。如果证据仍支持原判断,即使受到质疑,也要坚持该立场。
先归类,再发布。 记录用户对每个主题的回应。讲解完成后,将记录的所有内容——无论是主题回应还是自由备注——归为三类:已定结论,将转为评论草稿;问题,即评审者提出、必须先回答的问题——答案应来自代码、代码库的 ADR,以及 PR 所实现的设计文档(如有,应获取;设计与实现之间的偏差是重要的评审材料)——因为调查通常会推翻或重塑原本拟写的评论;以及舍弃项,不产生任何输出。随后与评审者逐个确认拟发布的评论——批量审批表格会重新制造此讲解流程旨在消除的信息过载——每条评论都应锚定到具体代码位置;若不针对具体代码,则锚定到文件级或 PR 级。全部确认后,通过可用的 GitHub review 机制,将它们作为一次 PR review 发布。评审发布后,本次讲解结束。
--canvasreferences/CANVAS_MODE.md