walkthrough-pr
Produce one continuous, readable PR review the user can read top-to-bottom. Same shape as
, plus a much heavier scrutiny pass. The user can have uncommitted changes in their main working tree — this skill never touches it.
Resolve scope
Arguments:
<pr-branch> [dest-branch]
.
is required.
- Try
git rev-parse --verify <pr-branch>
- If that fails, run once, then retry as and . Use whichever resolves.
- If still unresolved, stop and ask the user.
- If passed explicitly, use it (resolve same way as ).
- Otherwise, run
git symbolic-ref refs/remotes/origin/HEAD
refs/remotes/origin/<name>
- If that fails (origin/HEAD not set), stop and ask the user. Do not guess / / — better to ask than review against the wrong base.
Capture the PR head SHA via
git rev-parse <pr-branch>
for use in output and verification.
Set up the worktree
The review reads files from a detached worktree at
<repo-root>/.pr-review/<branch-slug>/
. The main working tree is never touched.
is the PR branch name with characters illegal in folder names (notably
, plus
,
,
,
,
,
,
,
) replaced with
. Examples:
→
;
→
. Strip any leading
first if the user passed a remote-tracking ref.
- First-run hygiene: ensure is in . Read the file; if the line is missing, append it. ( is per-repo and not committed, so this doesn't churn the team's .)
- Clear the same-branch worktree if present: if
<repo-root>/.pr-review/<branch-slug>/
git worktree remove --force .pr-review/<branch-slug>
- Create the worktree:
git worktree add --detach .pr-review/<branch-slug> <pr-branch-ref>
The worktree
stays alive after the skill finishes so clickable links in the review remain navigable. Re-running
for the same branch overwrites it; different branches accumulate side-by-side under
. The user can list them with
and prune stale ones with
git worktree remove --force .pr-review/<branch-slug>
.
Gather
All git commands run from the main repo (refs work without entering the worktree):
git diff --stat <dest-branch>...<pr-branch>
git diff <dest-branch>...<pr-branch>
git log <dest-branch>..<pr-branch> --format='%s%n%n%b'
When you need surrounding context that isn't in the diff (e.g. to see how a touched function is called elsewhere),
files via absolute paths under
<repo-root>/.pr-review/<branch-slug>/...
. Don't
from the main tree — that's the user's working state, not the PR's.
Decide reading order
Same heuristic as walkthrough — bottom-up by dependency:
- Schema / migrations / types / data models
- Pure utilities and shared helpers
- Core business logic (services, domain modules)
- Glue / handlers / controllers / API routes
- UI / views / templates / styles
- Tests
- Config, fixtures, docs, snapshots, lockfiles
Deviate when one file is clearly the entry point of the change — lead with it and treat the rest as supporting context. State the chosen order and reason up front.
Linking to lines
Whenever you call out specific code, link to it with a line-anchored markdown link pointing into the worktree, not the main repo. Clicking opens the actual PR-state file.
Format:
- Single line:
[validateInput](.pr-review/<branch-slug>/src/foo.ts#L42)
[src/foo.ts:42](.pr-review/<branch-slug>/src/foo.ts#L42)
- Range:
[the new error branch](.pr-review/<branch-slug>/src/foo.ts#L42-L58)
Pick line numbers from the
post-change side of the diff — the
in each
hunk header, then count down. Those numbers match the file at the PR head, which is what the worktree contains.
For deletions, there's no "after" line to link — describe the removal in prose and link surrounding context. Don't fabricate anchors.
Use prose link text ("the new error branch", "
") rather than raw
whenever it reads better.
Write the review
Compose the review as one continuous markdown document, then save and display it:
- Save the full content to
<repo-root>/.pr-review/<branch-slug>/WALKTHROUGH.md
- Display the exact same content inline in chat — no pagination, no "say next to continue". The chat output and the file content must be identical (single source of truth).
State up front in the document: "Links open files in
.pr-review/<branch-slug>/
, which holds the PR branch state. The worktree is overwritten on the next
run for this same branch." Substitute the real branch slug in the actual output — readers should see a concrete path.
1. Overview (2–3 sentences)
What this PR does and why, inferred from the code, commit messages, and any new tests. Mention the PR branch, the dest branch, the head SHA, and rough size (e.g. "9 files, ~240 lines added across X, Y, Z, against
(PR head
)").
2. Reading order
Short numbered list naming the files in the order you'll cover them, with a brief reason for the grouping.
3. File-by-file
One section per file (or per group, for trivial files). Each section:
- Heading: clickable worktree path, e.g.
[.pr-review/<branch-slug>/src/foo.ts](.pr-review/<branch-slug>/src/foo.ts)
- What changed — a summary, not a re-paste of the diff.
- Why — inferred intent; flag uncertainty.
- Scrutinize — anything non-obvious, risky, or worth a second look. Omit when there's nothing to flag.
4. Things to scrutinize (heavy pass)
A final section with cross-file concerns. Walk through each category below explicitly — even briefly stating "nothing here" — so nothing gets quietly skipped:
- Logic bugs & off-by-ones — boundary conditions, inverted comparisons, wrong loop variables.
- Tests — missing coverage for new branches; tests that assert nothing meaningful (e.g. only checking that something didn't throw); deleted tests; snapshot churn that hides logic changes.
- Error handling — swallowed exceptions, generic catches, missing fallbacks at boundaries (network, FS, deserialization), error states that silently succeed.
- Edge cases — empty inputs, nulls/undefined, zero-length collections, concurrency / race conditions, retry behavior, idempotency.
- Security — secrets in code or config, injection (SQL/shell/HTML), auth bypass, missing authz checks, unsafe deserialization, SSRF, prompt injection in LLM contexts.
- Scope creep — drive-by changes unrelated to the PR's stated intent; refactors mixed with feature work; formatting churn obscuring real changes.
- Accidental reverts — code that re-introduces something previously removed; stale code paths revived.
- Dependency changes — new packages, version bumps (especially major), unexpected lockfile churn, transitive risk.
- API / contract breaks — renamed/removed exports, changed function signatures, response shape changes — and whether call sites elsewhere in the repo were updated.
- Performance — N+1 queries, unbounded loops, sync I/O on hot paths, unneeded re-renders, large allocations in tight loops.
- Hallucinated APIs — calls to functions/methods that don't exist on the imported module (especially common in AI-generated PRs). Verify by ing the imported module from the worktree when in doubt.
- Leftovers — TODOs, debug logging, , commented-out code, dead branches.
If a category genuinely has nothing, say so in one phrase ("Tests: comprehensive, asserts the new branch."). If everything is clean, end with one sentence saying so.
Length and tone
- One paragraph per file for typical changes. Expand to several for non-trivial logic. Collapse trivial files (lockfiles, snapshots, mass renames, generated code) into a single grouped paragraph.
- The user already has the diff — don't paste large hunks back. Quote specific lines only when calling something out, and prefer a line-anchored link over a quoted block when the link alone is enough.
- Plain prose with markdown structure.
Footer
End the review with a one-line cleanup hint:
Worktree at
.pr-review/<branch-slug>/
(PR head
). Saved review:
.pr-review/<branch-slug>/WALKTHROUGH.md
— share this file as-is. To remove the worktree now:
git worktree remove --force .pr-review/<branch-slug>
. Other branches' worktrees under
are untouched — list them with
.
Substitute the real branch slug and SHA in the actual output.