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.

As the author

1. 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.

2. 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.

3. 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}}}}}}}'
   

4. Merge only under the repo's rules: CI green, a review exists, every thread resolved, and the user's go-ahead where the repo requires it (cad-agent: the user asks; product repos say in their AGENTS.md). 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. 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.