Pull request review

An author cannot review their own change: they read what they meant, not what they wrote. Every PR gets a review by an agent or person that did not write it, and the review lives on the PR, where anyone can see it later.

Scroll sideways to see the full diagram →

Diagram source

flowchart TD
    A["author: a reviewable PR<br/>what, why, how it was checked"] --> R["independent reviewer<br/>verifies, comments, verdict"]
    R --> F["author fixes or explains,<br/>replies, resolves every thread"]
    F -->|"changes"| R
    R -->|"pass on the head"| M["merge under the repo's rules"]
    class R,F here
    class A near
    class M out
    classDef here fill:#fffdf5,stroke:#173d3c,color:#173d3c
    classDef near fill:#eef1e4,stroke:#6f8a80,color:#173d3c
    classDef out fill:#ffe1cc,stroke:#bd3a12,color:#173d3c

As the author

Make the PR reviewable. Description: what and why, how it was checked (commands and their results, the real project it was tried on, renders or reports), effect on other projects, and Closes #<issue>. For geometry changes, run cad-agent all first. Every row passes, "Holes clear" included, and you have walked docs/common-issues.md. Push everything; the reviewer reads GitHub and the branch, not your session.
Ask for the review. In Claude Code, spawn the cad-pr-reviewer subagent with the PR URL and the checkout path. In Codex, start a separate session with the cad-pr-reviewer skill. Give it the PR, not your conclusions: a reviewer told what to find tends to find it.

Answer every comment on the PR. Fix it and reply with the commit (Fixed in <sha>: ...), or explain why not. Then resolve the thread:

gh api repos/<owner>/<repo>/pulls/<n>/comments/<comment_id>/replies -f body="Fixed in <sha>: ..."
gh api graphql -f query='mutation{resolveReviewThread(input:{threadId:"<thread id>"}){thread{isResolved}}}'
# thread ids: gh api graphql -f query='query{repository(owner:"<o>",name:"<r>"){pullRequest(number:<n>)
#   {reviewThreads(first:50){nodes{id isResolved comments(first:1){nodes{databaseId body}}}}}}}'

Merge only under the repo's rules: CI green, an independent review, every thread resolved.
- Repos with merge gates (cad-agent's cad-gates/... statuses) make these required checks. Only an independent reviewer's pass verdict on the head commit turns the review gate green, and agents may merge once every check passes and, just before merging, python3 tools/ci_gates.py all --repo <owner>/<repo> --pr <n> run from an up-to-date checkout of the integration branch (not the PR's copy) exits 0. It reads the reviews live, so a block posted since the last gates run stops the merge.
- Repos without gates say in their AGENTS.md whether the user's go-ahead is also needed.
- Merge commits, not squash, unless the repo says otherwise. After the merge, check that the linked issues closed and tick the tracking issue (cad-work-tracking).

As the reviewer

Read the diff (git diff origin/<base>...HEAD in a checkout of the branch, or gh pr diff <n>), the PR text and the linked issue. Do not edit, commit or push to the branch.
Verify before you post. Run the tests that cover the change; for a claimed bug, reproduce it with a small script. Report only what you checked. Mark severity: blocking, minor, nit.
For CAD and simulation changes, check the evidence, not only the code:
- geometry: does the exported STEP/STL match the claim (bounds, volume, clearance numbers in the reports)?
- physical assumptions stated and sourced: directions (fan flow, gravity, load), units, datum and orientation of any photo or drawing fit, which values are measured and which assumed;
- simulations: converged and steady, energy or force balance closed, mesh dependence acknowledged;
- nothing claims more than CAD can show (fit, strength and temperature are predictions until tested);
- the common-issues index, every row: each automatic check (for example "Holes clear") present in the report, passing and current. If one is missing, run it yourself without writing into the checkout (cad-agent holes --out /tmp/<scratch>/holes.json). Each review-only row is checked by looking at the model and named in the summary. A mistake the index does not list is a finding, and it is added to the index.
Post inline comments on the exact lines (gh api repos/<o>/<r>/pulls/<n>/comments with commit_id, path, line, side=RIGHT), then one summary review (gh pr review <n> --comment --body ...) that says plainly whether anything is blocking. Its last line is the verdict marker for the head commit you reviewed:  when nothing blocking is left, otherwise verdict=block. A re-review after fixes posts a new summary with a new marker. Where the repo has merge gates, re-run them so they read it: gh workflow run gates.yml -R <owner>/<repo> -f pr=<n>. Do not approve or merge unless the repo's rules give the reviewer that role.
Finish with a list of findings (file:line, severity, one sentence) for the author.