/walk-pr

name: walk-pr
description: 'Walk through a PR or large diff together — your own or someone else''s — one sub-changeset at a time and one review topic at a time within it. Use when reviewing a substantive PR collaboratively, walking a large refactor, or when the user asks to walk a PR, walk a diff, explain a PR, review collaboratively, or review a change together. Optional --canvas runs the walk in a live HTML artifact.'
argument-hint: '[pr-url-or-range] [--canvas]'
user-invocable: true

Walk 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.

**`--canvas`.** Load `references/CANVAS_MODE.md`. The HTML artifact **replaces** chat as the walkthrough surface — and it is a picture, not a document: one persistent system map of the PR with a stepped story, pinned review topics, comment-anywhere, and diffs in an on-demand drawer, generated once upfront and opened immediately. The user navigates self-paced and hands the consolidated review bundle back to chat, where the triage above takes over.