feat(pull-requests): guided reviews, a beta tour of a pull request
A large pull request is hard to start reading. Review agents already flag the bugs; what a maintainer needs is the shape of the change and the few calls only they can make.
This adds guided reviews behind a beta. Turning on Review guides in Settings ā Source Control adds a Guide tab to pull requests on that server. With it off, nothing changes: the tab, the menu item and the ready notices are all hidden.
What a guide is
A read-only agent reads the change in a temporary checkout of the head and writes a tour: stops in reading order, each with the lines that carry it, line-anchored notes, and a Look closely callout only where a maintainer has a call to make. The server holds the guide to the change. Excerpts are clamped to changed lines, notes must sit inside them, and every changed file lands in some stop.
- Written on demand, stored per pull request. "Write guide" or "Rewrite guide" is in the pull request's āÆ menu. A run takes minutes, so you can leave and you get a notice when it's ready or failed. The guide shows as stale after a push.
- Configurable. A project-scoped review guide model, and free-form instructions for your taste (what to show first, what to skip). Instructions can't change the format or coverage.
- Stacks. Each layer is briefed alone, measured from its parent branch. The agent sees the stack and may point to the layer that introduces or uses something, without touring it.
- Claude and Codex can write guides; other providers report that they can't.
Reviewing from the guide
- Comment on excerpt lines. Comments join the same pending review the Code tab collects, and Finish review on the last stop opens the composer with them.
- Ask an agent. A suggested question, Ask about this stop, or Ask agent on selected lines opens a thread with the stop as context. The guide stays open beside the new thread at the same stop.
Expanding hunks (all diff views)
The bars between hunks already expanded in the Code tab and the thread diff panel, but our stylesheet hid the button and squeezed the label. They are now visible controls everywhere, and guide excerpts and file diffs expand into the surrounding code too.
| Before | After |
|---|---|
 |  |
Notes for review
- New migration
061_PullRequestReviewGuidesstores one guide per pull request (lists in the migration tests updated). - New RPCs
pullRequests.reviewGuide(read) andpullRequests.generateReviewGuide(guarded write). - Not covered: per-turn diffs in the thread panel ("Latest turn") still can't expand, because the server has no file read at a checkpoint. That would be its own change.
Testing
- Typecheck clean (errors and warnings) in web, contracts, client-runtime, provider-core and server; lint has no errors; Knip passes.
- Web, contracts, client-runtime and provider-core tests in scope: 2765 passed. Server tests for pull requests, migrations, text generation, settings and auth: 615 passed, including a service test that runs a guide against a real git remote with a four-layer stack.
- Checked by hand in a browser against a dev server: the beta gate, writing and rewriting, notices, stops, comments, asks, stacks, links and expansion.
Update: the beta is a server setting
The beta gate moved from a client setting to a server setting (reviewGuidesEnabled, environment-wide), so agents follow the same switch as people. Off hides the Guide tab in every client and the server refuses to write a guide, with "Review guides are off. Turn them on in Settings ā Source Control." The service test covers the refusal. Agent tools that write guides are in #18143, stacked on this one.
Written by Claude Opus 5.5 in Claude Code.
š¤ Generated with Claude Code
Closes #17157