Add walk-pr skill

[wesrich]

Why?

A review tool says what is wrong. Nothing says where to look and what to decide — and those are different jobs.

This fell out of writing Copilot review instructions for a Rails app. That repo's review-scope file tells the automated reviewer to stay out of architecture, product intent, and business rules, because a human has to do those. Then the human gets handed a diff and no help doing exactly that part. walk-pr is the complement: instead of suppressing those findings, route them to the person as questions.

What Changed

• Added skills/walk-pr — emits a reviewer's guide in five sections: the spine (reading order), decisions the diff makes that its ticket doesn't settle, blast radius, what a user sees, and what it could not determine
• Listed it in the README's Developer Workflow table and in AGENTS.md
• Added a "Walk PR + Code Review" entry under How skills work together — they cover opposite halves

The three constraints do most of the work

Shorter than the diff, or it doesn't get read. Questions rather than verdicts, since defect claims belong in the code review. And it ends with what it could not determine — that section is the deliverable, not a disclaimer.

That last one is load-bearing. On the PR this was drafted against, two independent automated reviewers asserted the same fabricated detail — a value present in a seed file that wasn't there, cited down to the line number. Stating what the file actually contains and admitting the intent is unknown is more useful than either confident answer.

Testing

Run against a 13-file Rails feature PR whose defects were known in advance. The guide came to ~40 lines against a 167-line diff and surfaced the two worst problems — a calculation that was never called, and eight margin changes to a contract PDF that nobody had rendered — without claiming either was a bug.

One real bug found in drafting: computing blast radius from the base branch returns "0 call sites" for everything, because the code under review isn't there yet. That reads as a finding rather than a mistake. The skill now says to check out the head first.

Also run against a docs-only PR as a control, where the "if every file is mechanical, say so and stop" clause should fire.

Post-merge

• Run it on a few more PRs before treating the output contract as settled — two data points isn't enough to know whether five sections is the right number
• Decide whether this stays on-demand or becomes an automatic PR comment. My read is on-demand: the value concentrates in PRs where the reviewer already senses they're out of their depth, and an auto-comment on every dependabot bump trains people to scroll past it

Screenshots

N/A — no UI changes.

🤖 Generated with Claude Code

[julliancalkins]

Looks good for a first pass. We can always refine this later

[stephenfinch]

Suggested change

Those are different jobs, and the second one has no owner.

[stephenfinch]

I wonder if it might makes sense to include existing review comments in the skill context, feels like a lot of the value in this skill is to "bring the human up to speed" which would include existing discussions.

[stephenfinch]

this could flag a lot of RM PRs haha, not sure how to fix that...