Skip to content

High-level review

A high-level review is a checklist for judging a pull request without reading every line: whether its description is reviewable, whether the shape of the change matches what it says it does, and whether the few files where a mistake is expensive are right. Use it alongside an adversarial review, which does read every line.

Pick High-level review from a session’s Review menu, or ask an agent to /review-high-level [number] for the current branch’s pull request or pull request number. The checklist opens in the session’s preview pane.

The high-level review checklist for a pull requestThe high-level review checklist for a pull request
The high-level review checklist for a pull request

To get back to a review from the Review menu, pick Open high-level review while it’s open, or Reopen high-level review after closing it.

The agent first splits the pull request into slices, each one behaviour with its code, tests and wiring together, and puts whatever no slice claims in Everything else. It also writes steps for trying the change by hand. Reviewing the same commit again reuses them.

The rail on the left lists Overview, then each slice with its line counts and a dot for each item you’ve ticked. Pick an entry to see its items as tabs. Next slice, or [ and ], moves between entries on the same tab, and 1 to 9 pick a tab.

The slice rail with Overview, two slices with their line counts and tick dots, and Everything elseThe slice rail with Overview, two slices with their line counts and tick dots, and Everything else
The slice rail with Overview, two slices with their line counts and tick dots, and Everything else

Overview covers the whole pull request:

  • Description, the tab a review opens on, shows the pull request’s description, whether each description check passes and why, and the What and Why sections and linked issue the checks found.
The Description tab of a high-level review, with the description checks above the pull request's descriptionThe Description tab of a high-level review, with the description checks above the pull request's description
The Description tab of a high-level review, with the description checks above the pull request's description
  • Checks are worked out from the pull request itself and show whether they pass:
    • The description has a What and a Why section.
    • The description is under the word cap.
    • The pull request links the GitHub issue it resolves.
    • A UI change has a screenshot or video in the description.
    • The pull request has no merge conflicts.
The Overview checks of a pull request, passing and failingThe Overview checks of a pull request, passing and failing
The Overview checks of a pull request, passing and failing
  • Manual testing lists any setup, then numbered steps, each with what to do and what you should see. Links in a step open the page or the file on GitHub.
The manual testing steps of a pull request under OverviewThe manual testing steps of a pull request under Overview
The manual testing steps of a pull request under Overview
  • All files shows every changed file as a tree with its line counts, each tagged with the slices it’s in. Click a tag to go to that slice.
  • Related PRs asks whether a change that spans repos links its pull requests in the other repos, with the description beneath to check.

Each slice has its own items, ticked and commented separately:

  • Structure shows the slice’s files and changes as a tree.
The changed files of a pull request under the Structure itemThe changed files of a pull request under the Structure item
The changed files of a pull request under the Structure item
  • Tests lists the slice’s changed tests by name, grouped by file and describe. Click a test to see its source.
A slice's changed tests under Tests, with one test's source shownA slice's changed tests under Tests, with one test's source shown
A slice's changed tests under Tests, with one test's source shown
  • Critical diffs shows the full diff of each critical file the slice changes.
The full diff of a critical file under a slice's Critical diffsThe full diff of a critical file under a slice's Critical diffs
The full diff of a critical file under a slice's Critical diffs

In All files and Structure, click a file to open its diff, or follow its link to the file on GitHub. Expand all and Collapse all open or close every diff, and typing a file name or glob, or picking a Quick glob, lets Show or Hide just the matching diffs. Defaults puts every diff back as it started.

Select lines in a diff, a test’s source or the manual testing steps and type a note, then:

  • Send to agent types it into the session.
  • Add to review adds it to the comments posted with the review. Comments on lines in the pull request’s diff are posted on those lines.

Comments added to the review are listed under Queued for review at the foot of the pane. Press ✎ on one to edit its note, or ✕ to remove it.

  • Approve, Comment or Request changes posts your verdict to the pull request as a GitHub review, with your item comments, each slice’s under its title, and queued comments. Unless you approve with no comments, what will be posted opens for approval first.
  • Close posts nothing and keeps your ticks and comments, so reopening the review picks up where you left off.
  • Start fresh discards this commit’s ticks and comments and has the agent slice the pull request again.
The Start fresh button in the high-level review's footerThe Start fresh button in the high-level review's footer
The Start fresh button in the high-level review's footer

Reopening a review of the same commit brings back its ticks and comments. Tick Force re-run in the Review menu to start again.

Ask an agent to /review-config and it proposes globs for the repo’s critical, UI and collapsed files, with the files each one matches, for you to approve or comment on before they’re saved. Or set them yourself:

Terminal window
assist config set review.highLevel.criticalPaths "**/*.graphql,src/i18n/*.json"
assist config set review.highLevel.uiPaths "src/ui/**"
assist config set review.highLevel.descriptionWordCap 300
assist config set review.highLevel.testPaths "**/*.test.ts,e2e/**/*.spec.ts"
assist config set review.highLevel.collapsedPaths "**/*.test.*,**/generated/**"
Key Default Sets
criticalPaths see below Files whose full diffs Critical diffs shows
uiPaths none, so no screenshot is required Files that make a change a UI change, needing a screenshot or video
descriptionWordCap 300 The most words the description can have
testPaths **/*.{test,spec}.{ts,tsx,js,jsx} Test files whose tests Tests lists
collapsedPaths **/*.test.*, **/generated/** Files whose diffs start collapsed under Structure

Unset, criticalPaths covers GitHub workflows and actions, package.json, Dockerfiles (Dockerfile, Dockerfile.*, *.Dockerfile) and CLAUDE.md, anywhere in the repo. Setting it replaces these, so list them too if you still want them.

From the command line, assist review --high-level --configure asks for each key in turn, suggesting globs for any that are unset.