pr-review
Skill1 starsChanged 52 days agoMITView on GitHub
Review a GitHub pull request by orchestrating reviewer + oracle sub-agents directly from the orchestrating session, consolidating their findings into a single report, and asking for approval before posting. Interactive by default; set PR_REVIEW_MODE=post to post the review as a plain comment without asking, for headless dispatch. Use when user says "review PR #N", "review pull request", "review this PR", "review N on owner/repo", provides a PR URL, or asks for a PR review.
- Deletes or force-pushes
- Commits and pushes
195 other projects use a version of this.
Adopted by
Most recently taken up by
- neomjs/neo-agent-skillstheir own version, first seen Nov 15, 2026
- asarelcastellanos/claude-workbenchtheir own version, first seen Nov 15, 2026
- NVIDIA/cclustertheir own version, first seen Nov 15, 2026
- jellydn/my-ai-toolstheir own version, first seen Nov 15, 2026
- richkuo/rk-skillstheir own version, first seen Nov 14, 2026
- Significant-Gravitas/AutoGPTtheir own version, first seen Nov 14, 2026
Used with
Projects with it also use oss-pr, pr-automation and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
CES-LtdSkilloss-pr
Use when creating a pull request, after committing changes, or when user invokes /oss-pr. Covers branch management, quality checks, commit, push, and PR creation.
Also in 3 projects that use this
CES-LtdSkillpr-automation
PR Automation Orchestrator: poll open PRs, check CI, run review, fix, and merge eligible PRs. Use when: (1) Invoked by daemon via scripts/pr-automation.sh, (2) User says "/pr-automation".
Also in 3 projects that use this
jtenniswoodSkillexpert-reset
Reimagine this repository from first principles using the current product and user experience as the target. Use when the user says "/expert-reset", asks how the project should be rebuilt if starting again, wants bold architecture or component-structure recommendations, or wants a research-only reset plan unconstrained by current implementation details.
Also in 3 projects that use this
jtenniswoodSkillupdates
Summarize user-facing project updates from the last 7 days, ordered by importance and written as one-sentence "Feature: description" entries. Use when the user says "/updates", asks what changed recently, or wants a concise list of recent features, device support, fixes that users will notice, or other product value.
Also in 3 projects that use this
openchamberSkillclack-cli-patterns
Use when creating or modifying OpenChamber CLI commands, prompts, terminal output, non-TTY behavior, `--quiet`, or `--json` behavior.
Also in 3 projects that use this
openchamberSkilldrag-to-reorder
Use when implementing or modifying OpenChamber sortable or drag-to-reorder behavior, especially `@dnd-kit`, touch/mobile interactions, variable-width items, or wrapping layouts.
Also in 3 projects that use this
- +6 more from openchamber
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- Significant-Gravitas/AutoGPT★ 188ksame name
- pytorch/pytorch★ 106ksame name
- rtk-ai/rtk★ 87ksame name
- saadeghi/daisyui★ 43ksame name
- rustfs/rustfs★ 36ksame name
- dotnet/maui★ 23ksame name
- NVIDIA/Megatron-LM★ 18ksame name
- MiniMax-AI/skills★ 14ksame name
- openchamber/openchamber★ 13ksame name
- btriapitsyn/openchamber★ 13ksame name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- action-patternSkill
- adr-creationSkill
- boost-documentation-searchSkill
- bug-fixSkill
- component-composition-patternsSkill
- creating-pull-requestsSkill
- github-cli-workaroundsSkill
- html-outputSkill
- inertia-react-conventionsSkill
- javascript-typescript-conventionsSkill
- monthly-report-generatorSkill
- pest-testing-conventionsSkill
- refactor-comments-that-are-code-smellsSkill
- routing-and-controllersSkill
- serena-conventionsSkill
- serena-mcp-selectionSkill
- settings-systemSkill
- single-task-responsibilitySkill
- spatie-data-transfer-objectsSkill
- tdd-laravelSkill
- troubleshooting-backendSkill
- troubleshooting-frontendSkill
- troubleshootingSkill
- unexpected-situationsSkill
- wayfinder-conventionsSkill
- write-a-skillSkill
- writing-skills-readme-firstSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. 0 are common, 21 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 179 edited versions we read keep these.
21
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 27
Read the mode, do not infer it — it is one command, and the default leaves interactive use exactly as it was:
- Very specific: line 72
If a phase genuinely did not happen — a leg died, the review was not posted — stamp the moment you decided that.
- Distinctive: line 88
If the owner/repo cannot be determined from the task or the git remote, ask the user before proceeding.
- Distinctive: line 104
Check whether the user explicitly mentioned the non-master target in their request (e.g., "review PR #123 which targets develop").
- Distinctive: line 105
If the user did NOT explicitly mention it: Stop immediately. Report:
- Distinctive: line 107
Do not proceed with the review.
- Distinctive: line 116
Check whether the current working directory is inside a git repo:
- Distinctive: line 141
If the fast-forward fails, stop and ask the user rather than forcing anything.
- Very specific: line 177
Check 3 — Not in a repo with the right remote: Ask the user: diff-only review (fast, GitHub API) or full clone (slower, better).
- Distinctive: line 187
Before reviewing, confirm the branch still integrates with master.
- Distinctive: line 232
Wait for the user's decision: before doing anything else.
- Very specific: line 355
If no worktree was created (diff-only mode), tell both children to use gh pr diff <number> --repo <owner/repo> and note they will not have …
- Very specific: line 359
Do not block. Keep responding to the user.
- Distinctive: line 432
Write the sanitised report there.
- Distinctive: line 487
Never block or re-run a step to tidy up a measurement.
- Distinctive: line 526
Write the line even when the review is not posted (user declined, or a leg died): a killed review is exactly the evidence needed for "this …
- Distinctive: line 528
Never write findings prose here.
- Distinctive: line 581
After any inline fixes are committed, run the pipeline again to catch auto-fixes your changes introduced:
- Distinctive: line 626
Shape B — the code is right but nothing pins it: Write the test; it starts green, because there is no defect to reveal.
- Distinctive: line 640
If step 10 assigned findings to buckets, append the disposition line and the three bucket groups — Inline fix first, then Issue, then …
- Very specific: line 654
Before posting, verify the report body matches the verdict: Read through $REPORT_FILE and confirm that:
- Distinctive: line 660
If there is a mismatch, fix the report body first, then post.
- Distinctive: line 720
Verify the comment is visible on the PR before moving on.
- Distinctive: line 724
When the user says "clean up review <number>": only when the PR has been merged or closed.
- Very specific: line 726
Delete ${XDG_RUNTIME_DIR}/pr-review/$number/ (review artifacts directory)
- Distinctive: line 727
If the user created a worktree for this review, ask them whether to remove it — do not remove it yourself
- Distinctive: line 741
When any of the four disagrees, repair the workspace before reading anything — check the PR head out into it, or ask the user when the …
“Common” is measured: kept by at least 6 in 10 of the 179 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PR Review
You are the orchestrator of the PR review. You run the reviewer and oracle sub-agents directly as your own children — there is no intermediate review agent. This flat shape is intentional: both children appear in your fleet with live per-child detail (model, context mode, tool/token/elapsed counters, current activity), so a working-but-slow child is distinguishable from a stuck one, and a stuck leg can be steered or re-dispatched individually without losing the other leg's work. Never reintroduce a wrapper agent for this flow.
Before starting any review, read guide.md — it contains hard-won lessons and constraints that prevent real failures (timeout budgets, context mode, baseline rules). This is not optional. GLOSSARY.md beside it fixes the vocabulary — leg, finding, disposition, verdict, split — and
names the words not to use for each. Use its terms in the report, in the record and in anything you post,
because the same thing under two names is how a review ends up arguing with itself.
Review artifacts directory
Review artifacts (context file, report) must live in a RAM disk, not in the project directory. The correct location is ${XDG_RUNTIME_DIR}/pr-review/$number/ where XDG_RUNTIME_DIR is the user-specific runtime directory (typically /run/user/$(id -u)). Check it with echo $XDG_RUNTIME_DIR — it defaults to /run/user/1000 on most Linux systems. Do NOT create review artifacts inside the project worktree — it pollutes the working tree and risks them being committed.
Mode: present or post
The skill runs in one of two modes, chosen by the caller:
| Mode | Set by | Behaviour |
present (default) | nothing | Review, present the report, wait, then post it as an approval or a request for changes |
post | PR_REVIEW_MODE=post | Review, then post the report as a plain PR comment without asking. No inline fixes, no commits, no pushes, no issues, no approval, no change request |
Read the mode, do not infer it — it is one command, and the default leaves interactive use exactly as it was:
MODE="${PR_REVIEW_MODE:-present}"
case "$MODE" in
present|post) ;;
*) echo "unknown PR_REVIEW_MODE='$MODE' (expected present or post)" >&2; exit 2 ;;
esacWhy the gate exists, and why post removes it. Present mode exists so a human can read the report and interact — fix a finding, ask a question, revise the wording — before it goes public. A dispatcher has no such human, so the gate becomes a stall: the only answer it could ever give is "post it". post states that answer in advance, and changes nothing else about the review itself.
post mode is advisory by design. It never edits, commits or pushes, so it needs no write access to code, and a comment it posts can be withdrawn or edited. That is what makes it safe to run unattended over a queue: the worst a mistaken or manipulated review can do is leave a wrong comment on a pull request. It also means every finding stays the author's to fix — the review recommends, it never acts.
The variable belongs to the caller. This skill defines the two values and no others, and names nothing about who is calling it.
Workflow
0. Open the split-time log
Split times are captured as each phase ends, never reconstructed afterwards. A bash call is its own shell, so a variable set in step 4 is gone by step 9 — the stamps therefore go into a file, one append per phase:
SPLITS="${XDG_RUNTIME_DIR:-/tmp}/pr-review/<number>/splits.tsv"Each stamp is this command, with the name substituted; the file (and its directory) are created by the first append:
mkdir -p "$(dirname "$SPLITS")" && printf '%s\t%s\n' <name> "$(date +%s%3N)" >> "$SPLITS"| Stamp | Emit at | Means |
t0 | here, before any preflight | skill activated |
preflight_end | end of step 3 | PR parsed, worktree ready, context and standards files written |
legs_start | step 4, after both launches have returned | both legs are running |
legs_end | step 5, the moment the last leg returns | both legs finished |
assembly_end | end of step 9 | consolidation, reversal check, sanitisation and report write done |
t4 | step 13 after posting — or immediately before the final answer when the review is not posted | delivered |
Emit t0 now. Then emit each remaining stamp at the step named, as that phase ends.
If a phase genuinely did not happen — a leg died, the review was not posted — stamp the moment you
decided that. A legs_end recorded at the instant you gave up on a leg is true and useful; a stamp
you leave out because the step did not run cleanly is a measurement you lose for good. Step 9.5
treats a missing stamp as a failure and says so.
1. Parse the request
Extract the PR number and optional owner/repo from:
| Input format | Extracted |
Review PR #44 | number=44, repo from git remote |
Review PR #44 on owner/repo | number=44, owner/repo given |
https://github.com/owner/repo/pull/44 | number=44, owner/repo parsed from URL |
owner/repo#44 | number=44, owner/repo parsed |
If the owner/repo cannot be determined from the task or the git remote, ask the user before proceeding.
1.5. Resolve the PR, then verify it targets master (hard gate)
Fetch the PR's branches before any workspace decision. Step 2's "already on the PR branch" check compares the current branch against headRefName, so fetching it later makes that check impossible to evaluate — that ordering bug is why an already-checked-out PR branch gets missed.
gh pr view <number> --repo <owner/repo> --json number,title,url,state,headRefName,baseRefNameHold PR_HEAD, PR_BASE, and PR_TITLE for the rest of the workflow. If state is not OPEN, say so and confirm the user still wants a review.
Now the target-branch gate. Do not skip it.
If PR_BASE is not master:
- Check whether the user explicitly mentioned the non-master target in their request (e.g., "review PR #123 which targets develop").
- If the user did NOT explicitly mention it: Stop immediately. Report:
⚠️ PR #
<number>targets<PR_BASE>, notmaster. This PR appears to be aimed at the wrong branch. Aborting review to avoid wasted effort. Please verify with the PR author. Do not proceed with the review. Do not merge master. Do not run any review steps. - If the user DID explicitly mention it: Continue, but note the non-master target in the context file and in your final report.
If PR_BASE is master: proceed to step 2.
Running this before the workspace questions means a mis-targeted PR is rejected without ever asking the user where to work.
2. Choose the review workspace (current directory first)
Check whether the current working directory is inside a git repo:
TOPLEVEL="$(git rev-parse --show-toplevel 2>/dev/null)" || TOPLEVEL=""
CURRENT_REMOTE="$(git remote get-url origin 2>/dev/null)"
CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
WORKTREE_PATH=""Check 1 — Already on the PR branch. This is the expected case, not a lucky one. The user normally checks out the PR branch into a worktree and starts the session there, so check the current directory first and prefer it. A match requires all three:
CURRENT_REMOTEis the same repo as<owner/repo>— compare owner/repo, not the raw URL (git@github.com:<owner>/<repo>.gitandhttps://github.com/<owner>/<repo>.gitboth count)CURRENT_BRANCHequalsPR_HEADgit status --porcelainshows no modified tracked files (see the guard below)
On a match: set WORKTREE_PATH="$TOPLEVEL" and continue. Do not ask the user where to work, do not offer alternatives, do not create or switch anything. Asking here is the exact failure this check exists to prevent. Then bring the branch up to date:
git fetch origin "$CURRENT_BRANCH"
BEHIND="$(git rev-list --count HEAD..origin/"$CURRENT_BRANCH" 2>/dev/null)"
if [ "$BEHIND" != "0" ]; then
git merge --ff-only origin/"$CURRENT_BRANCH"
fiIf the fast-forward fails, stop and ask the user rather than forcing anything.
Guard — dirty working tree. Before doing any review work, verify the review directory is clean. Run git status --porcelain and stop if there is any output — modified tracked files, untracked files, new files, deleted files, or staged changes. Previous reviews, abandoned experiments, or other branches may have left debris. Report the full git status --porcelain output and ask the user whether to commit, stash, or discard everything before proceeding. Ignored build artifacts (see step 2b) do not count — they are expected. Do not review over a dirty tree; it produces false findings and makes it impossible to tell which changes belong to the PR.
Check 2 — Same repo, different branch. The directory is the right repository but not the PR branch. Compare the directory's path with the branch it is holding before deciding anything — the user keeps one worktree per branch, named for it in full (src/master, src/develop, then one per ticket branch under whatever prefix that branch uses: src/chore/<ticket>, src/feat/<ticket>, src/tickets/<ticket>), so the name is an assertion about the contents and their navigation depends on it. Never parse the prefix — it is chore/, fix/, bugfix/, hotfix/, docs/, refactor/, or nothing at all, and it changes — so compare the whole path suffix against the whole branch name. Only the generic ones (src/wip, src/review/wip) change branch by design. That gives one test with no list of magic names to maintain: does the directory's path name the branch it holds?
| Path names… | What it means | What to do |
PR_HEAD | This worktree is the PR branch's home; the checkout was simply forgotten | Confirm, then check out PR_HEAD here, and recommend it plainly |
the branch it holds, not PR_HEAD (master, develop, staging, or any other branch under any prefix) | Another branch's home. The name promises those contents | Do not offer this directory and do not switch it. Name the mismatch and ask where to work — this is the case that needs a scratch worktree or a new one |
| neither | Scratch space, reused across reviews on purpose | Offer it as the default (below): a clean tree means the switch was forgotten, not that the directory is taken |
Compare words, not characters — case and separator style are cosmetic, so hotfix/Payments-Down and hotfix/payments_down are one name. Compare the whole path, not the basename, and keep the prefix in the comparison: src/feat/issue-96-dashboard names feat/issue-96-dashboard and src/chore/install-vitest names chore/install-vitest, though neither basename carries the prefix.
norm() { printf '%s' "$1" | tr 'A-Z' 'a-z' | tr '_-' '//'; }
ends_with() { case "$1" in *"$2") return 0;; esac; return 1; }
held="$(git branch --show-current)" # the branch this directory currently holds
if [ -z "$held" ]; then echo "generic (detached HEAD) -> offer, default yes"
elif ends_with "$(norm "$PWD")" "$(norm "$PR_HEAD")"; then echo "names PR_HEAD -> switch here"
elif ends_with "$(norm "$PWD")" "$(norm "$held")"; then echo "another branch's home -> do not offer"
else echo "generic -> offer, default yes"; fiFor a generic directory or one named for PR_HEAD:
- Check out
PR_HEADin the current directory — the default whenevergit status --porcelainis empty. Confirm with the user and recommend it. Rungit fetch origin "$PR_HEAD", thengit checkout "$PR_HEAD". If the checkout is refused, fall through to option 2 or 3 rather than forcing it. - Use a different existing worktree — especially one already named for
PR_HEAD. Rungit worktree listand go there. - Let the user create one — ask them to create/check out a worktree and tell you the path.
Do not create worktrees yourself — creation needs project-specific setup beyond git — but checking out an existing branch in an existing worktree is not creation. If the user nonetheless directs you to use a directory named for another branch, follow the instruction and say which branch it will hold, so the exception is theirs and on the record rather than silent.
A dirty tree blocks the switch: clear it through the guard above first, then offer this choice. Set WORKTREE_PATH to whichever path results, and announce it in the pre-flight line below before any further step.
Step 16 re-checks the branch before any later read, for the same reason this step may switch it: the directory is shared, and it can move under you between turns.
Check 3 — Not in a repo with the right remote. Ask the user: diff-only review (fast, GitHub API) or full clone (slower, better). Diff-only means both children use gh pr diff <number> --repo <owner/repo> and have no surrounding codebase.
Workspace pre-flight — announce it before continuing. Post one line stating the resolved workspace and branch before any further step, for example:
Workspace:
/path/to/worktree— branchfeat/x, PR #<number>headfeat/x✓, basemaster✓
This makes a wrong workspace visible immediately instead of surfacing 40 minutes later as bogus findings. If the announced line disagrees with the PR, stop and fix it before step 2a.
2a. Merge master into the PR branch (conflict check)
Before reviewing, confirm the branch still integrates with master. This catches merge conflicts early and confirms the branch merges cleanly. The merge itself is then discarded (below), because it is a probe, not a change to the PR.
Fetch latest master:
cd "$WORKTREE_PATH"
git fetch origin masterMerge master into the PR branch:
git merge origin/master --no-edit 2>&1
MERGE_EXIT=$?Interpret the result:
| Outcome | Action |
| Merge succeeds (exit 0) | The branch integrates cleanly. Drop the merge again (below), then proceed to step 2b. |
| Merge conflicts | Stop. Report the conflicts to the user and ask for a decision. Do not auto-resolve. |
The merge is a conflict probe, not a change to the PR — drop it before you commit anything.
This step answers one question: does the branch integrate with master? It is answered the moment the merge succeeds, and the merge commit then has no further job. Leaving it in place is what makes the later pushes awkward: every commit the review makes sits on top of a commit the remote has never seen, and the tempting fix is to rebase your work onto the PR head to get rid of it. Never do that — rebase is forbidden (guide.md, Hard constraints). Reset instead, and do it now, while nothing of yours is committed:
git reset --hard origin/"$PR_HEAD"The branch is exactly the author's head again, every commit this review makes lands on it directly, and each push is a plain fast-forward. What this step contributes is the finding — "master merges cleanly" — which belongs in the context file and the report, not a commit.
Do not skip the reset and push the merge commit instead "because it is a fast-forward anyway". It would be one, but it puts a merge into the PR's history that the author did not make, and the next agent reading the branch cannot tell whose merges are whose.
If there are merge conflicts:
- Abort the failed merge:
git merge --abort - Report to the user:
⚠️ Merge conflicts detected when merging
masterinto<headRefName>. This means the PR branch is out of date with master.How would you like to proceed?
- Fix the conflicts now — I'll resolve them and commit, then continue with the review.
- Hand back to the PR author — ask them to merge master themselves before the review.
- Abort the review — stop here.
- Wait for the user's decision before doing anything else.
2b. Build production assets (before the pipeline)
Generated frontend artifacts are gitignored, so a freshly checked-out worktree starts with whatever a previous build left behind — not what this branch needs. Wayfinder route and action definitions, Inertia/Ziggy helpers, and the Vite manifest are all in this category. When the branch adds or renames routes, tsc then fails on phantom errors such as Property 'form' does not exist on type '...RouteDefinition...' in files the PR never touched. Those errors burn review budget and mask real findings. They are caused by an unbuilt workspace, not by the branch, so the remedy is to build — never to report them, and never to dismiss them as pre-existing.
Build the assets so the workspace matches production before anything type-checks against it:
cd "$WORKTREE_PATH"
# choose the package manager from the lockfile:
# bun.lock(b) → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm
bun run buildLook for a build script in package.json — in Laravel + Wayfinder projects it is typically php artisan typescript:transform && vite build, and vite build is what regenerates resources/js/actions and resources/js/routes. A production build of a large app can take several minutes; give it a generous timeout and do not interrupt it. The shell tool's timeout is in seconds, not milliseconds — timeout: 900 is generous for a large app, whereas 900000 is read as ~10 days and rejected outright (Invalid timeout: maximum is 2147483.647 seconds), so the build never runs. This is different from a child's timeoutMs, which is milliseconds (7_200_000 = 2h). Context-mode's timeout is also milliseconds: timeout: 900000 for the same build — the value the shell tool rejects.
Interpret the result:
| Outcome | Action |
| Build succeeds | Proceed to step 2.5. Commit nothing — build outputs (public/build, generated route definitions) are gitignored. |
| Build succeeds but modifies tracked files | Commit them as auto-fixes (git add -A && git commit -m "chore: regenerate build artifacts"), then proceed. If the diff is substantial rather than obviously generated, stop and ask the user. |
| Build fails because dependencies are missing, or artifacts are absent or stale | Fix it. Install dependencies and rebuild, then re-run. This is yours to solve, not a finding to report. |
| Build fails on the branch's own code (a dangling import, a type error) | Stop. This is a PR finding and a blocker — report it with the failing output. It is not an environment defect, and the review must see it. |
| No frontend build script (backend-only repo) | Skip this step, note it, and proceed to step 2.5. |
If generated-artifact errors appear anyway — a missing Vite manifest, missing properties on Wayfinder definitions — do not classify them as pre-existing and do not hand them to the review. Run the build and re-run the pipeline. An error the merge would ship is an error, whatever produced it: production does not care that it predates the diff. Only a build that fails on the branch's own code is reportable, and then it is a blocker, not an environment note.
Why before the pipeline, not after: composer fix runs tsc, and tsc reads those generated definitions. Building afterwards validates a different tree than the one that failed. See guide.md for the rationale.
2.5. Establish green baseline
Before doing any review work, run the project's quality pipeline in the worktree to confirm a green starting point. This is non-negotiable: if you review against a dirty baseline, pre-existing failures become your noise, not the PR author's signal. Production assets are already built (step 2b), so tsc type-checks against current generated definitions rather than whatever a previous build left behind.
Run the pipeline:
cd "$WORKTREE_PATH" && composer fix 2>&1This runs Pint (formatting), Biome (JS/TS linting), Pest (tests), and tsc (type-check) in one shot — the standard Laravel quality pipeline.
Interpret the result:
| Outcome | Action |
| All green, no file changes | Proceed to step 3. Clean baseline confirmed. |
| All green, but Pint/Biome auto-fixed files | Commit and push the fixes immediately — capture the fixer's output (git status --porcelain before and after composer fix, stage only the files the fixers touched, commit and push) — so the branch starts green and the PR contains the code about to be reviewed. Then proceed to step 3. |
Do not use
git add -A. Capturegit status --porcelainbefore and aftercomposer fix, diff the two snapshots, and stage only the files that changed.git add -Awould sweep unrelated working-tree changes into a commit labelled “style” and push them to the PR. |
Staging pattern:
git status --porcelain > /tmp/before-fix.txt
composer fix 2>&1
git status --porcelain > /tmp/after-fix.txt
# Stage only files the fixers actually touched:
comm -13 <(sort /tmp/before-fix.txt) <(sort /tmp/after-fix.txt) | awk '{print $2}' | xargs git add
git commit -m "style: quality pipeline auto-fixes"
git push origin "$CURRENT_BRANCH"| Test failures or type errors | Stop. Report the failures to the user. Ask whether to fix them first or proceed with the review knowing the failures pre-exist. Do not proceed silently. |
Push the auto-fixes before launching the review — do not stop at committing. A local-only commit means the review validates code the PR does not contain, and GitHub's diff still shows the unformatted version. Pushing mechanical formatting fixes back to the PR branch is normal pre-review sync, not a review change. If the push is rejected (no write access, protected branch), report it and ask whether to continue with the fix committed locally only.
Push every formatting correction, including files this PR does not touch — Boy Scout rule. Do not filter the auto-fix diff by whether a file appears in the PR's own changes. Formatting is the project's declared standard (Pint/Biome config), so correcting drift applies the standard rather than expressing an opinion, and the change is semantically inert. More importantly, in these projects nothing else will ever make the correction: CI runs the pipeline in fix mode (composer fix, composer pint, biome check --write) with no dirty-tree check, so drift is rewritten inside the runner and discarded, and the auto-commit step that would have pushed it is normally disabled. Drift inherited from master therefore persists forever unless a review pushes it — and because every review's baseline pipeline re-formats the same files, it resurfaces on every PR until corrected. Do not revert those files and do not defer them to a separate PR. If the report mentions them at all, it is only to label them mechanical pre-review formatting sync, never as an out-of-scope defect.
The review target is the resulting HEAD — the complete PR as it will merge. HEAD now contains the author's commits plus any pre-review auto-fix commits just pushed. That whole entity is what gets accepted into master, so it is what the reviewers judge: never scope a review to the author's original commit, and never to a SHA resolved before this step. In the worktree the reviewed diff is everything from the merge base:
git diff $(git merge-base HEAD origin/master)..HEAD --statTip: If you're unsure why we run the pipeline before reviewing, or what to do with the results, check
guide.mdfor the rationale.
3. Gather PR metadata, the whole conversation, and previous review history
Pass both children the path to the committed standards file:
STANDARDS_FILE="$(dirname "$0")/standards.md" # skills/pr-review/standards.mdIt fixes severity (🔴 / 🟡 / ❔) and owns the finding-label vocabulary. It is read by reference, not copied into the context file, so amending it changes the next review without editing any prompt.
PR_HEAD, PR_BASE, and PR_TITLE are already resolved (step 1.5). This step adds the description, file manifest, commits, and the whole conversation.
Read the whole conversation, not just the description. A PR is a dialogue: a developer answers a review question, confirms a decision, or corrects the review's reading of the code in a comment, because that is what the comment box is for. A review built from the description and the reviews alone re-asks questions that have already been answered and reports answered items as open, which reads to the author as though the conversation was never opened. All four reads are required:
gh pr view <number> --repo <owner/repo> --json number,title,body,headRefName,baseRefName,files,additions,deletions,author,state,createdAt
gh pr view <number> --repo <owner/repo> --json commits
gh api "repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100" --jq '.[] | select(.state != "PENDING") | {id: .id, user: .user.login, body: .body, state: .state, commit_id: .commit_id, submitted_at: .submitted_at}'
gh api "repos/<owner>/<repo>/pulls/<number>/comments?per_page=100" --jq '.[] | {id: .id, user: .user.login, body: .body, path: .path, line: .line, diff_hunk: .diff_hunk}'
gh api "repos/<owner>/<repo>/issues/<number>/comments?per_page=100" --jq '.[] | {id: .id, user: .user.login, body: .body, created_at: .created_at}'The last read is the discussion thread, and it is the one that gets dropped: pulls/.../comments returns review comments, while the author's reply to a review arrives as a discussion comment, so a round that fetches only the first three cannot see an answer at all. gh pr view <number> --repo <owner/repo> --comments prints the description and the whole thread in one read — keep it as the sanity check that nothing was missed.
A reply that answers a review question closes that item. When the author comments "confirmed X was the target" or "no change needed here", the item is answered: mark it ✅ in the report and do not carry it forward as still open. Re-asking an answered question is a review defect rather than caution, and it was never the author's fault for answering where comments belong. A reply is an answer, so it outranks an inference from the code or the description.
Check any factual claim inside a reply against the code. The two are not in tension: the decision a reply makes is the author's to make, and the fact it asserts is testable. A reply can be honest and still wrong about what the code does — for example one that says a change was scoped, when the same commit also removed a value other surfaces depended on. Honour the decision; verify the fact.
Extract a compact summary: title, description, file list (path + additions + deletions), commit SHAs and messages, base branch, head branch, all previous review comments and change requests, and every discussion comment in chronological order with its author and timestamp. Record each previous review's commit_id — that is the SHA GitHub recorded for the round, and it is the only reliable way to tell what state a previous finding referred to once the branch has moved. Use it when reconciling change requests in step 6 and when checking for reversals in step 7.
Write the shared context file — one file both children read, so task strings stay short and the two legs work from identical input:
REVIEW_DIR="${XDG_RUNTIME_DIR}/pr-review/$number"
mkdir -p "$REVIEW_DIR"
CTX_FILE="$REVIEW_DIR/context.md"It contains: PR number/repo, title, description, file manifest, commit list, base/head branches, the review workspace path, the full previous review history (all prior review bodies and inline comments including change requests), and the whole discussion thread in chronological order — every comment with its author, timestamp and body. The thread is where the author answers the review, so a round cannot reconcile change requests without it.
4. Launch reviewer and oracle in parallel
Read children.md now — it contains the exact task templates for both agents and the launch script.
Launch both as direct children in one async workflowScript with runs.all. Both use context: "fresh", cwd: $WORKTREE_PATH, and an explicit generous timeoutMs. Task text references the shared context file rather than duplicating it.
If no worktree was created (diff-only mode), tell both children to use gh pr diff <number> --repo <owner/repo> and note they will not have full codebase access.
5. Monitor while they run
Do not block. Keep responding to the user. The two children are yours: check subagent({ action: "status", view: "fleet" }), tail a leg's transcript, and use /subagents-fleet for live per-child detail (steer s, stop D).
Liveness signal: a leg whose tool/turn/elapsed counters are advancing is working, even if it has produced no output for a while — a 45-minute review with test runs is normal. A leg whose counters are frozen for a long stretch may be stuck.
Failure recovery — one leg at a time: if a leg fails, times out, or is stopped, re-dispatch only that leg with the same agent and task (optionally with resume if its run is retained and resumable). Do not restart the healthy leg. A completed leg's output is preserved; proceed with what you have rather than burning the whole wave.
Tip: If a leg appears stuck or fails, check
guide.mdfor failure recovery guidance.
6. Consolidate
Merge the two reports into one structured document:
- Standards — from the reviewer's Standards findings
- Spec Fidelity — from the reviewer's Spec findings
- Pattern Consistency — from the oracle's pattern/architecture findings
- Authorisation & Scoping — from the oracle's auth findings
- Risk Areas — from the oracle's risk findings
- Previous Review Follow-up — only when previous reviews exist: per-request status (✅ addressed / still open written severity-then-❌, e.g.
🔴❌🟡❌❔❌), reconciled against both the author's replies in the discussion thread and the code at HEAD — an item the author has answered in a comment is ✅ addressed even when the code never changed. Still-open items carry forward as repeat findings. - Tests to add — the tests the production-code findings call for, red-first where the code is currently wrong
- Most actionable before merge — your own prioritised list
Glyph vocabulary — one meaning each. 🔴 blocker, 🟡 warning, ❔ minor, for findings that are still open; ✅ for fixed this round or verified correct, with the severity dropped; ⚠️ for reversal notes only. 🟢 is never a finding marker — it appears only in the Bottom line verdict, where green means "no problem, go". The red X is reserved for follow-up reviews and means you were asked for this and did not fix it: write it after the severity of a previously-requested item that is still open (🔴❌, 🟡❌, ❔❌), never on a new finding and never in an initial review. Open the report with the legend on one line so the code is self-describing, and name the three buckets beside it — Inline fix, Issue, Decision (step 10). Findings carry their bucket as a bracketed tag after the severity glyph, e.g. ❔ [Inline fix] …, and the buckets are presented as separate groups in step 10's order, never interleaved. The bucket labels are words rather than glyphs, so the glyph vocabulary above stays one-meaning-each.
Never write a bare number for a GitHub artefact. Issues and pull requests share one numbering sequence per repository, so #221 is ambiguous by construction and a reader cannot resolve it. Write PR #221 or issue #223 everywhere — headings, tables, prose, and anything that will be posted (review bodies, PR comments, issue bodies, commit messages). The prefix is required even when the surrounding context seems to make it obvious, because these lines are usually skimmed in isolation.
Findings that require a change to production code carry a Test: line. A defect in shipped behaviour is evidence that the suite has a hole, so the finding answers: which test should have caught this — Test: <suite/file> — <assertion that fails without the fix>? This is the preferred remedy, not an absolute one. State the reason on the same line when a test is impractical (a query-plan regression, a timing behaviour) or when the fix cannot be expressed as a test at all (a name that only reads badly), and name the owning workstream when the test belongs to other work — another ticket or a declared follow-up — so it is tracked rather than lost with the review. Skipping the line silently is the one thing not allowed: a preference nobody has to account for is a preference that quietly stops being followed.
Findings that need no production-code change carry no Test: line. A stale PR description, a plan doc naming a class that no longer exists, an ADR that contradicts shipped behaviour, a naming or readability observation: the remedy is an edit to the prose or to the shape of the code, and inventing a test for them is category confusion. Where an automated check would genuinely have caught one — a reference check that fails when a documented class is deleted, a shared constant that makes a wrong label unrepresentable — name it, because that check is worth having. Otherwise say plainly that the remedy is prose.
Untested behaviour is worth flagging, and it is not the same as behaviour that is wrong. Code that is correct only because nothing pins it will drift on the next touch, so name the missing test. But the test starts green, so it cannot be written red-first — it is a guard to add, not a defect to reveal. Flag it as a test gap and let the author schedule it; it does not carry the weight of wrong behaviour.
Issues keep full depth (code snippets, impact, fix recommendations, file/line references). Confirmed-correct items collapse to terse "✅" one-liners. Do not merge or rerank across axes — keep sections separate.
Append a "What's Correct" appendix collecting every confirmed-correct item into one checklist, then the Bottom line verdict as the very last block:
- 🟢 APPROVE — no blockers, no warnings, fewer than 3 ❔ minors (safe to track as follow-ups)
- 🟡 CONSIDER NOT APPROVING — no hard blockers, but any 🟡 warning or 3+ ❔ minors
- 🔴 DO NOT APPROVE — one or more 🔴 blockers
Format (exactly one line plus a one-sentence reason):
---
## Bottom line
🟢 **APPROVE** — no blockers, no warnings; only [N] minor nit(s), safe to track as follow-ups.
Reason: [one sentence — the single most important factor behind the verdict]7. Check for contradiction reversals
Before sanitising, cross-check every change request in the new report against the previous review history and the author's replies to it (both from the context file). A reversal is a new request demanding the opposite of what a previous review asked for (rename X→Y then Y→X; action-class→service-class then back; extract-then-inline; approve-then-reject-code-that-was-approved). Refinements in the same direction, requests about new code, and repeats of never-implemented requests are NOT reversals.
For each reversal, read the actual code in the worktree, weigh both arguments against project conventions and the PR's intent, then:
| Determination | Action |
| New recommendation is clearly correct | Keep it + add ⚠️ Reversal note: explaining the earlier recommendation and why it is walked back |
| Previous recommendation is clearly correct | Drop the new request; move it to "Confirmed correct" with a one-line explanation |
| Genuinely ambiguous | Do not include in the report; escalate to the user for arbitration with the tradeoff summarised |
8. Sanitise
Remove all internal process references from the report before presenting: no "reviewer", "oracle", "sub-agent", "orchestrator", "context: fresh", "worktree", "delegation", or methodology talk. Write as if you performed all the analysis yourself — "I" or "We", never "the reviewer found" or "the oracle noted". The PR author should see a clean, professional review.
9. Write the report to a file
REPORT_FILE="$REVIEW_DIR/report.md"Write the sanitised report there. The file lives in the review workspace and survives for follow-up questions.
9.5. Split times
Record the splits; do not narrate them in the report. A review is long enough that the shape of its cost is worth knowing, and knowing whether 18 minutes is the legs or the assembly changes what to optimise — but a timing block on every report is noise. So: always measure, log into the record, and show the numbers only when asked (or in the aggregate over the record).
Derive them from the stamps emitted in step 0. Those values are epoch milliseconds, so the differences are already milliseconds:
declare -A S
while IFS=$'\t' read -r k v; do S[$k]=$v; done < "$SPLITS"
missing=()
for k in t0 preflight_end legs_start legs_end assembly_end t4; do
[ -n "${S[$k]:-}" ] || missing+=("$k")
done
if [ ${#missing[@]} -eq 0 ]; then
TIMING=$(jq -nc \
--argjson t0 "${S[t0]}" --argjson p "${S[preflight_end]}" \
--argjson ls "${S[legs_start]}" --argjson le "${S[legs_end]}" \
--argjson a "${S[assembly_end]}" --argjson t4 "${S[t4]}" \
--argjson rev "${REVIEWER_MS}" --argjson ora "${ORACLE_MS}" \
'{t0:$t0,
preflight_ms:($p-$t0),
dispatch_ms:($ls-$p),
legs_ms:($le-$ls),
assembly_ms:($a-$le),
delivery_ms:($t4-$a),
total_ms:($t4-$t0),
reviewer_ms:$rev,
oracle_ms:$ora,
timing_complete:true}')
else
TIMING=$(printf '%s\n' "${missing[@]}" | jq -R . | jq -sc \
'{timing_complete:false, timing_missing:.}')
echo "⚠ TIMING INCOMPLETE — missing stamp(s): ${missing[*]}" >&2
fiREVIEWER_MS and ORACLE_MS are each leg's own elapsed time, as returned by its launch.
Two facts that make the numbers mean something:
- The legs run in parallel, so the splits overlap.
reviewer_ms + oracle_msexceedslegs_ms, and that is correct, not a bug —legs_msis the wall clock from the first launch to the last return. - Only
total_msis a duration a human experiences. Preflight and assembly are the parts you control; the legs are the parts the model controls. If total grows, check which one before reaching for anything else.
Never block or re-run a step to tidy up a measurement.
A missing split is loud, never silent. The record is still written — the findings are worth more
than the timings — but it carries timing_complete:false and the names of the stamps that never
landed, and the run says so in its own output. Six nulls look exactly like a fast review to
anybody reading the log a month later, which is worse than having no timing at all.
9.6. Append the review record
One line per review, appended to the durable log — this is the only artefact that outlives the run, and the only way a recurring finding can ever be spotted. The RAM-disk report is deliberately ephemeral; the log is deliberately not.
REVIEW_LOG="${REVIEW_LOG:-$HOME/.pi/agent/state/reviews.jsonl}"
mkdir -p "$(dirname "$REVIEW_LOG")"
printf '%s\n' "$(jq -nc \
--arg date "$(date -Iseconds)" \
--arg repo "<owner/repo>" \
--argjson pr <number> \
--arg sha "$PR_HEAD_SHA" \
--arg verdict "<approve|request-changes|commented|not-posted>" \
--argjson legs '{"reviewer":"<ok|died|timeout>","oracle":"<ok|died|timeout>"}' \
--argjson counts '{"blocker":N,"warning":N,"minor":N}' \
--argjson labels '["<label>"]' \
--arg mode "$MODE" \
--arg comment_url "${COMMENT_URL:-}" \
--argjson timing "$TIMING" \
'{date:$date,repo:$repo,pr:$pr,sha:$sha,verdict:$verdict,mode:$mode,comment_url:$comment_url,legs:$legs,counts:$counts,labels:$labels,timing:$timing}')" >> "$REVIEW_LOG"labelsis the de-duplicated set of labels fromstandards.mdthat this review actually raised. A fixed vocabulary makes recurrence aGROUP BY, not a text search:jq -r .labels[] "$REVIEW_LOG" | sort | uniq -c | sort -rn.timing.legs_msis the longer leg, not the sum — the legs overlap.timing.timing_completeisfalsewhen a split stamp never landed, andtiming.timing_missingnames it. Those rows are still worth keeping for the findings, but exclude them from timing statistics or a broken measurement re-enters the average as if it were a fast review.- Write the line even when the review is not posted (user declined, or a leg died): a killed review is exactly the evidence needed for "this keeps happening".
- Never write findings prose here. The line records what kind, how much and how long — never what was said.
Then answer timing questions from the log rather than from memory. Everything below is minutes;
total_min/total_mean/total_max are the likely band for planning a batch, and rows with an
incomplete measurement are counted but excluded from the statistics:
jq -s '[.[] | select(.timing.timing_complete)] as $r
| { reviewed: length,
timed: ($r|length),
incomplete: (length - ($r|length)),
total_min: (($r|map(.timing.total_ms)|min) / 60000),
total_mean: (($r|map(.timing.total_ms)|add / ($r|length)) / 60000),
total_median: (($r|map(.timing.total_ms)|sort|.[length/2|floor]) / 60000),
total_max: (($r|map(.timing.total_ms)|max) / 60000),
median_legs: (($r|map(.timing.legs_ms)|sort|.[length/2|floor]) / 60000),
median_assembly: (($r|map(.timing.assembly_ms)|sort|.[length/2|floor]) / 60000)
}' "$REVIEW_LOG"10. Bucket every finding and recommend a disposition
Assign every finding to exactly one of three buckets, and present each bucket as its own group, in this order:
- Inline fix — anything the review can correct in this session: prose, formatting, a comment or docblock, a name, a dangling reference, a missing test, a behaviour change pinnable with a red-first test, a small refactor. Size is never a reason to knock a finding back to the author. A finding leaves this bucket only when it needs a decision the review cannot make, needs access the review lacks, or belongs to work owned elsewhere.
- Issue — a finding that must not be fixed in this PR: out of scope, cross-cutting, or needing its own scheduling. Propose a title and an assignee — the PR author by default, the operator for administrative or data tasks that need their access.
- Decision — a finding whose remedy needs a choice only a human owns: product behaviour, whether a built-but-unrouted feature ships, a trade-off between defensible options, a deploy or production-data call, or access the review lacks. Give the options, the pros and cons of each, and your recommendation, so accepting the recommendation is a one-word answer.
The grouping and the order are deliberate: never interleave the three buckets in one table or list. Inline fix comes first because approving that group unblocks work immediately; the other two can then be considered at leisure.
Lead with the recommended disposition — Inline fix: 7 (~2h) · Issue: 3 · Decision: 0 — so the operator's default answer is "accept", with per-item overrides. Flag any inline fix estimated over ~30 minutes, touching more than three files, or changing behaviour beyond the finding it fixes, so it can be vetoed individually. The disposition line is also the operator's signal of how much work the review is taking on.
Do not fix anything yet. Fixing is the review's recommendation, never its own decision — wait for authorisation.
Red-first applies to every production-code fix, whatever its size. A finding that changes production code carries a Test: line and is fixed test-first (step 11.5): write the test against the unchanged code, watch it fail for the right reason, then fix, then revert the fix to confirm the test still fails. An inline fix that skips this leaves the suite as blind as it was when the finding was found, and a silent fix is never acceptable — every fix is listed in the report with its commit and its test. Prose-only findings carry no test line.
An inline fix is still a change, so it is committed and pushed like any other (step 11).
In present mode, present the report (step 12) with the disposition and a note like:
Recommended disposition: Inline fix: [N] (~[effort]) · Issue: [M] · Decision: [K]. Want me to fix the inline group now?
Then:
- Operator accepts → Fix the inline findings, commit each, proceed to step 11, then propose the issues for approval (step 14).
- Operator overrides → Apply the overrides; leave everything not authorised for the author.
In post mode, there is nobody to authorise anything, so the buckets are structure for the comment and nothing more. State the disposition line as a recommendation — Recommended disposition: Inline fix: 7 (~2h) · Issue: 3 · Decision: 0 — and never ask. Fixing is off the table (see Mode), so the line reads as advice to the author, not as a question.
11. Run quality pipeline on your changes (only if inline fixes were applied)
post mode never fixes anything, so this step and step 11.5 are skipped entirely. There are no changes of its own to pipeline, no commits to push, and no red-first ordering to honour — the review reports and stops. Reading them is still worth it: they are the standard the comment asks the author to meet.
After any inline fixes are committed, run the pipeline again to catch auto-fixes your changes introduced:
cd "$WORKTREE_PATH" && composer fix 2>&1| Outcome | Action |
| All green, no file changes | Proceed to push. |
| All green, but Pint/Biome auto-fixed files | Commit the fixes immediately — capture the fixer's output (git status --porcelain before and after composer fix, stage only the files the fixers touched), commit, and proceed to push. |
Do not use
git add -A. Same rule as step 2.5: stage only the filescomposer fixchanged.git status --porcelain > /tmp/before-fix.txt composer fix 2>&1 git status --porcelain > /tmp/after-fix.txt comm -13 <(sort /tmp/before-fix.txt) <(sort /tmp/after-fix.txt) | awk '{print $2}' | xargs git add git commit -m "style: quality pipeline auto-fixes"
| Test failures or type errors caused by your fixes | Revert your changes. Do not post broken code. Report the failure to the user. |
Push all commits before presenting. Baseline auto-fixes from step 2.5 were already pushed before the review launched; this covers commits made after it. After any inline fixes (and auto-fixes) are committed, push immediately:
git push origin "$CURRENT_BRANCH"Do not skip this. An unpushed commit means the merged PR will not contain the fixes you just made — the approval is posted on code that doesn't include your changes.
If the push is rejected as non-fast-forward, or you find a local merge commit under your work, reset — never rebase. A rebase rewrites commits, and the moment one of them is on the remote it needs a force push to land. Step 2a drops its merge commit precisely so this cannot arise; if it does anyway, get your work back onto the PR head without rewriting anything: git reset --hard origin/"$PR_HEAD" and cherry-pick your commits from a backup branch (a cherry-pick creates new commits, so nothing on the remote is rewritten). Never git push --force, and never rebase a commit that is already on the remote — merge instead.
Same rule applies after the review is posted. If the user asks you to fix findings on the PR branch later, treat every
composer fixrun the same way: checkgit difffor auto-fixed files, commit them, and push before declaring the task done. The pipeline discipline does not stop at step 13.
11.5. Red first — fixing a production-code finding
A defect in shipped behaviour means the suite had a hole, so the fix is not complete until the suite closes it. Work in this order — for your own fixes, and (stated in the posted review) for the author's. It applies to findings that change production code; a prose-only finding has no test step.
Shape A — the code is wrong.
- Decide the test. Name the suite and the file (Pest feature/unit, Pest arch, Vitest component, lint rule) and the assertion that has to fail.
- Write it against unchanged production code.
- Run it and record the failure — the test must fail, and fail for the reason the finding describes. A test that passes before the fix does not reproduce the finding, so fix the test until it does. This is the point of the exercise: it proves the defect is real and that the test can detect it.
- Only then change production code — the smallest change that turns the test green. Never fix first and back-fill the test afterwards: a back-filled test is written to match the implementation, so it can no longer detect the defect.
Shape B — the code is right but nothing pins it. Write the test; it starts green, because there is no defect to reveal. Its value is the guard, so validate it the same way: break the implementation temporarily, confirm the test fails, then restore.
For both shapes: re-run the full suite and the quality pipeline (step 11's discipline: composer fix, stage only fixer-touched files, commit, push); confirm the test is a real guard by reverting the production change and watching the test fail again before restoring it — a test that stays green when the fix is removed is documentation; and commit the test with the fix when a test applies, because a fix commit with no test leaves no evidence the hole was closed.
When a test is genuinely impractical, the fix still ships and the reason is recorded in one clause, naming the check that would catch it instead. When a previous round's fix is re-checked, the same standard applies: a change request counts as addressed if a test now fails without it, or the report says why no test applies.
12. Present for approval
In post mode there is no approval gate. Do the thread re-read and the report write below — both exist for correctness, not for the gate — then go straight to step 13. Do not ask "post it?", do not wait, and do not treat the absence of an answer as a reason to stop.
Re-read the discussion thread before presenting. The review ran for 45–90 minutes, so the author may have replied while it did — re-run the issues/<number>/comments read from step 3 and compare the timestamps with the context file. If a reply has answered an outstanding question or corrected a point, close or amend that finding in the report before presenting it. A review that arrives asking about something already answered on the PR spends the author's time and shows the conversation was never opened.
Write the full report contents as your actual response text — copy the Markdown directly into what you say to the user. Do NOT summarize it. Do NOT just read it into a tool output block and describe it. The user reads the report inline.
If step 10 assigned findings to buckets, append the disposition line and the three bucket groups — Inline fix first, then Issue, then Decision, as separate groups (step 10) — and ask about the inline group:
Recommended disposition: Inline fix: [N] (~[effort]) · Issue: [M] · Decision: [K]. Want me to fix the inline group now?
Then ask: "Post it? Revise something? Don't post?" — and act on the answer:
- Post it → Step 13
- Revise X → update REPORT_FILE, then re-present
- Don't post → stop; the report stays on disk (tell the user they can say "post the review of PR #
<number>" later)
If the user approved inline fixes in step 10 (and those fixes have been applied and pipeline-validated in step 11), re-present the updated report before posting.
13. Post the review
Before posting, verify the report body matches the verdict. Read through $REPORT_FILE and confirm that:
- Every finding that was fixed inline (step 10/11) has been updated in the report body — not just the Bottom line. If a 🟡 finding was fixed, its text should now say ✅ (fixed) or be removed entirely. A report that still says "🟡 X is broken" in the body but shows 🟢 APPROVE in the Bottom line will confuse the PR author.
- The Bottom line verdict matches the remaining findings. If all 🟡/🔴 findings were fixed inline, the Bottom line should be 🟢 APPROVE and the body should contain no unresolved warnings.
- Nothing in the report asks a question the author has answered in the discussion thread since the report was assembled — re-check that thread, as step 12 does. The user's read of the report takes time too, and an author can reply in the meantime; amend the report body before posting.
If there is a mismatch, fix the report body first, then post.
A request for changes asks for the tests alongside the fixes it asks for in production code. Section 7 names each test, its file and its assertion, and step 11.5 fixes the order; say in the review body that the test for a production-code finding comes with the fix, and that a fix landing without one leaves the suite as blind as it was. Prose-only findings need no test — do not pad the review with synthetic ones. Lead the requested-changes section with the tests, then the code changes.
Determine the review state from the report's Bottom line, then post.
present mode — a human has read it and said post, so the verdict is theirs too:
if grep -q '🟢 \*\*APPROVE\*\*' "$REPORT_FILE"; then
REVIEW_STATE="--approve"
else
REVIEW_STATE="--request-changes"
fi
gh pr review <number> --repo <owner/repo> $REVIEW_STATE --body-file "$REPORT_FILE"post mode — a comment, never --approve and never --request-changes. An automated first pass has not earned a verdict on someone's merge, and a review that blocks a merge with nobody standing behind it is worse than a comment the author can read and judge:
MARKER="<!-- pr-review:${PR_HEAD_SHA} -->"
COMMENT_FILE="$RUN_DIR/comment.md"
{
printf '%s\n\n' '**Automated review — not a final review.** This is an automated first pass, posted while no reviewer was available to read it beforehand. It is a comment: it is not an approval and not a request for changes, and it neither blocks nor unblocks the merge. Expect a human follow-up; treat the findings as a starting point.'
cat "$REPORT_FILE"
printf '\n%s\n' "$MARKER"
} > "$COMMENT_FILE"
# One comment per head SHA: a re-review of the same commit edits what is already
# there rather than adding a second.
EXISTING_ID=$(gh api "repos/<owner/repo>/issues/<number>/comments" --paginate \
| jq -r --arg m "$MARKER" '.[] | select(.body | contains($m)) | .id' | tail -1)
if [ -n "$EXISTING_ID" ]; then
jq -n --rawfile body "$COMMENT_FILE" '{body:$body}' \
| gh api -X PATCH "repos/<owner/repo>/issues/comments/$EXISTING_ID" --input - --jq .html_url
else
gh pr comment <number> --repo <owner/repo> --body-file "$COMMENT_FILE"
fiHold the URL it prints as COMMENT_URL for the record (step 9.6). If the post fails, fail the run out loud — a review that reviewed and did not post is a failed run, not a quiet one, and a dispatcher told it succeeded on one will never notice.
The traffic light stays, and gains one honesty clause. The report's Bottom line keeps its 🟢/🟡/🔴 verdict. In post mode the comment must also say plainly, in its first line after the banner, when the review is partial — a leg that died or timed out, a baseline that could not run, a suite that was absent. "One leg did not complete; these are the reviewer's findings alone" is the sentence. A clean verdict over a dead oracle is the one thing this mode must never publish.
Sanitisation matters more here, not less. In present mode a human reading the report is the last check on leaked paths, credentials, internal hostnames and half-finished reasoning. With that check removed, step 8 is load-bearing: no local paths, no artefact paths, no harness or session detail, no credentials, nothing about the machine it ran on.
14. Offer to escalate outstanding findings to GitHub issues
Skip this step entirely in post mode. Creating issues needs an explicit yes and there is nobody to give one, so unfixed findings are named in the comment as follow-ups for the author or the operator to raise.
Propose a GitHub issue for every finding left unfixed once the disposition is settled — whether the review is posted as an approval or as a request for changes — so nothing is lost between rounds. This is the Issue bucket from step 10, presented with a proposed title and assignee: the PR author by default, and the operator for administrative or data tasks that need their access. Group only what shares a subsystem or fix class; keep self-contained fixes as their own issue. Check gh issue list for duplicates first, present the proposed list, and wait for an explicit yes — never create issues unprompted. Skip documentation-only items and anything another issue tracks.
Link the created issues from the PR (review bodies are immutable, so links go in a comment):
# every issue body references the PR in the exact form: PR #<number>
gh pr comment <number> --repo <owner/repo> --body "Outstanding follow-ups from the review: #<n> #<n> …"Verify the comment is visible on the PR before moving on.
15. Cleanup
When the user says "clean up review <number>": only when the PR has been merged or closed. If the PR is still open, remind them the report and context file are active reference material and suggest waiting.
- Delete
${XDG_RUNTIME_DIR}/pr-review/$number/(review artifacts directory) - If the user created a worktree for this review, ask them whether to remove it — do not remove it yourself
16. Follow-up questions
Re-check the workspace before you trust any read of it. The review directory is a shared worktree, deliberately reused across reviews, and it gets switched to other branches between sessions. A session that ended on the PR branch can reopen on a different one, and every git or grep result then describes the wrong tree. A grep for a symbol the PR added returns nothing on a branch that never had it — which reads exactly like the author having fixed it. The failure is silent and confident, so it survives scrutiny: this has already produced a near-miss, where a ledger correct in every other respect was one command away from being posted about the wrong branch.
cd "$WORKTREE_PATH"
git fetch origin "$PR_HEAD"
git branch --show-current # must equal PR_HEAD
git rev-parse HEAD # must equal the PR head SHA, not an earlier reviewed commit
git status --porcelain # must be empty before any read is trustedWhen any of the four disagrees, repair the workspace before reading anything — check the PR head out into it, or ask the user when the switch was theirs and other work is in flight.
The children's reports are in your session's context and the report/transcripts are on disk. Answer codebase questions directly, run tests the reviewer flagged, or revise the report on request. A completed leg can be resumed with subagent({ action: "resume", id, message }) when its run is retained/resumable.
17. Review post-mortem (optional)
When the user says "run the review post-mortem" (or "post-mortem"), produce the standard metrics analysis: for each leg (reviewer, oracle) report duration, tool-call mix (serena_* vs bash vs read/grep/find), turns, tokens (input/output/cache-read) and cost where available, with diff-size context, and compare against previous rounds. Attribute differences honestly (diff size vs serena vs test infrastructure). Note: serena availability is machine-dependent — a run with no serena calls is not a defect and must never be flagged as one; the review flow is identical with or without it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

