Pull requests
Review a teammate's PR, answer the review on yours, present yours, and sweep everything on GitHub waiting on you. You paste every comment; only your own PR's description is applied for you, once you approve it.
In short
Four playbooks for pull requests: review a teammate's, answer the review on yours, present yours, and sweep everything on GitHub waiting on you. Switch on the GitHub pack first, then ask "review PR 142" with a real PR number.
Code review is where a human gates what agents write, and pull requests now arrive faster than anyone can read them. The engineer skill's PR playbooks let you walk into that conversation understanding the change better than anyone else in it, holding verified defects rather than impressions, with the words already written. A review is held to the same principles and playbooks your agent uses on its own code. Whose PR it is picks the playbook, and you can name one directly.
| Playbook | Whose PR | Ask | What you get |
|---|---|---|---|
| pr review | a teammate's | "review PR 142", engineer review 142 | The change explained, verified findings, and every comment ready to copy |
| pr replies | yours | "reply to the comments on my PR", engineer replies 142 | Every thread judged against the code, the accurate ones fixed, a reply for each |
| pr walkthrough | yours | "help me present #142", engineer walkthrough 142 | A standup script, the diff tour, the reviewers' questions, a recording runbook |
| github sweep | yours and your teammates' | "github sweep", engineer sweep | Everything waiting on you on one page, with a reply drafted for each |
All four use the GitHub pack. You paste every comment and reply, so nothing reaches a teammate without you deciding it should: see What the playbooks never do. Every report lands in <HOME>/reports/reviews/ and shows up in the next session's start context.
No PR yet? "Simplify and interrogate this branch" runs the same review on your own branch first, fixes what it verifies, and drafts the description: see Interrogate. For a different model on your own work, code or not, see Second-model review.
Reviewing a teammate's PR
you > review PR 142The review treats the PR as wrong until the code proves otherwise. The title, body, and commit messages are claims to test, not context to trust. It ends in one report page, in the order you read: understand, judge, act, then reference.
- The verdict and why: approve, approve with fixes, needs discussion, changes requested, or do not merge.
- Where to look: the few hunks to read yourself, what to skim, the decisions the PR makes for you (a default, a limit, a timeout, an error message), and the linked issue's criteria marked met or not.
- The description, checked: each claim in the PR body marked as matching the head, partly, wrong, or missing, with an accurate replacement to paste, folded behind a toggle.
- How it works: a call tree per flow, a walkthrough of the files, and before-and-after rows with small diffs of behavior as a caller sees it.
- Architecture, on a large feature: the components today and the target drawn in the same columns, a concerns table, the mapping onto the target interface, file-layout and code-skeleton comparisons, the debt, and a path.
- The case against: the strongest argument against merging, the most likely way it bites in three months, and what to cut if 40% had to go.
- Findings and questions as cards anchored to file and line, each a scenario with its proof and snippet. A point someone already raised becomes a reply on their thread, never a second comment. Those replies, and test and lint findings, sit lower, collapsed and badged.
- Reference: the file map with each file's comments inside it, every bot comment's outcome, what was verified clean, the checks that ran, and a summary comment for the conversation tab.
Five flags trade depth for speed or point the review at one layer of a stack.
Named on your own PR, engineer review 142 runs the full lanes as a self-review.
A second run is a re-review. When an earlier review of the same PR exists, the lanes run on what changed since it (plus its blast radius), the description is checked again, the local checks run in full, and the page opens with a Since last review delta above the findings.
The throwaway review worktree is removed once the report is saved. One holding uncommitted work or unpushed commits stays, and a worktree on your own branch is never touched.
Stacked PRs
A PR is in a stack when its base is another open PR's branch, or another open PR is based on it. Whichever layer you name, the review covers the whole stack from its edge, the PR nothing is based on, so a layer that only makes sense with the next one is judged with it.
The report, the findings, the threads, the summary comment and a re-review each change for a stack.
Answering the review on your own PR
you > what did reviewers say on my PR
you > address the review on my branch
you > engineer replies 142The replies playbook pulls every thread and works through it:
- Sorts the threads. A resolved thread is skipped. One you answered last needs only the Resolve click, or a follow-up when the code has since made your answer false. One someone else answered last needs a reply.
- Judges each comment against the current head, not the snapshot it was written on.
- Fixes what is accurate in the working tree, uncommitted, so
git statusis the reviewable set. Each fix follows the bug-fix playbook at the size of the defect (reproduced, fixed at the cause, a failing test first when the repo wants one), gets the comment pass, and comes with a suggested commit message you can copy. - Pushes back on what is wrong, with receipts.
- Reviews your own diff. A bounded self-pass runs the correctness, invariants, and regression lanes, so you find your own defect before the reviewer does.
- Writes a reply for every thread, in PR scroll order.
On the page, each thread is a card with your reply, a Copy button, and a link to the exact comment on GitHub, and a filter shows only the replies still to post.
A bot's confidence is not evidence; its comments get the same treatment. The exception is a bot's security, data, migration, or concurrency claim, which is never dismissed on a reading alone: it is disproved with a run or put to you.
Under --quick there is no worktree, so replies are drafted and nothing is fixed.
Presenting your own PR
you > help me present #142
you > engineer walkthrough 142 --rehearse
you > engineer walkthrough 142 --check ~/Desktop/pr-142.mp4The walkthrough is for the PR you are about to defend at standup or on a recorded test video. It rebuilds the change hunk by hunk from the diff, the task, and the sessions that wrote it, classifies each hunk by how hard it is to defend, and verifies the build locally. The doc it writes is meant for a hidden second screen:
- a two-minute standup script;
- the diff tour in the order GitHub shows it;
- the questions a reviewer will ask, with the receipts to answer them;
- a scene-by-scene recording runbook that covers every path the change adds, not only the happy one.
Every receipt is labeled by how well it is known, the way the why playbook labels evidence. A hunk you cannot defend becomes a gap with an action (simplify, revert, ask, or fix the PR description), never a bluff.
| Flag | Effect |
|---|---|
--rehearse | The room's questions, one at a time, with your misses corrected against the code |
--check <video> | Did the recording cover every scene |
A review of the same PR later reads the walkthrough as your stated intent and test plan and checks the diff against it.
Everything waiting on you
you > github sweep
you > what do I owe on GitHub
you > engineer sweepThe sweep covers the configured repo or the one you name. The github_sweep tool decides what is owed from GitHub's own fields, not from reading the text:
- unresolved threads where someone else spoke last;
- comments after your last word;
- mentions and review requests;
- a re-review a push made due;
- a review you started and left pending;
- pull requests that conflict with main.
Read-only drafters then work in parallel, related threads together. Each judges every owed comment against the branch head, writes a reply in your voice labeled confirmed, strong or unverified, and says when the code has to change before the reply can be true. A draft from an earlier review or replies page that was never posted is reused.
The page folds everything by issue, each PR under the issue it closes, then your own PRs, the reviews you owe and teammates' PRs. Every reply has a Copy box, filters narrow the page to one person, people only or new only, and a Handled tick per comment survives a re-render. Above the folds sit up to ten ranked first moves, each re-checked at its source, the code changes needed before a reply, the conflicts, and a line you can say at standup.
Your promises. The sweep lists the commitments you made in replies over the last 30 days ("I'll…", "in a follow-up", "before merge") and checks each one where it was made. Each is marked open, done (with the commit, PR or issue that did it), superseded, or wrong when its premise turned out false. The next sweep carries the list forward and checks each one again.
PR descriptions to paste. Drafters compare each of your own PRs, quiet ones included, with its branch head. When the title or body no longer matches (stale numbers, a removed feature, later commits that change behavior), they write the complete new title and body. A pushed branch that should become a PR gets the same, with its base and a compare link to open it.
The descriptions sit right after the first moves, one fold per PR, each with a Copy for the title and the body clipped past eight lines until Show all. A rewritten description comes back with its Handled tick cleared. Nothing is applied: the sweep stays read-only against GitHub.
Between sweeps. The next sweep picks up from the last one and drops what GitHub shows as answered. Each run refreshes the attention queue so the dashboard agrees with the page. Sync counts what is waiting, without reading any comment, and offers a sweep when something is.
The report page
A review or a replies run ends in one page you read beside the PR and paste from, opened in your browser.
Every card has a Copy button; how the cards preview, how long failures are written, and the checks the page passes are below.
How the review works
You can use a review without reading this. It says where the findings on the page come from.
What the playbooks never do
- Never post to GitHub or any chat surface: no comment, approval, or resolved thread. You paste. The one exception is your own PR's title or description: once you have seen the old and new text side by side and approved it, the agent applies it with
github_pr_update. A teammate's PR is never edited. - Never commit on a teammate's branch or check it out; a review runs on a throwaway worktree at the PR head.
- Never commit or push. Fixes on your own branch stay in the working tree for you to commit.
- Never put private material in a paste block: nothing from the agent home's memory or notes, no secrets, no customer identifiers.
Second-model review
Put a different model on anything you made, a proposal, a plan, a document, or code. It documents what it finds on one dossier; your agent verifies every finding, fixes the real ones, and hands back the next round.
Worktrees
Parallel agents on one repo with zero collisions, and a skill that creates and bootstraps the checkout for you.