Review and Ship a Change

A review answers what is wrong with a change. A commit records selected work. A pull request asks for that work to land. They have different outputs and approval boundaries. Asking for a review does not authorize edits, posting a public comment, committing or merging.

Use this guide to review someone else’s PR without adopting its code, or to finish your own change. It is not a requirement to run every review route before delivery. The PR lane already dispatches the reviewers its path matrix requires.

The work, from your side

Scope → verdict → commit → pull request

For your own change. For an inbound PR, stop at the local verdict unless you explicitly ask to post a comment. Typed completion still requires the applicable installed-host authority.

1. 01

   You choose the target

   Confirm the scope

   What you get

   The named working diff, path or inbound PR diff, with its current source identity.

   Before moving on

   Check the repository and branch. A failed PR fetch must stop, not silently review a different diff.

   Inspect review targets →
2. 02

   codeArbiter reviews; you decide

   Read the verdict

   What you get

   One triaged finding list with severity, file location and remediation guidance.

   Before moving on

   Resolve blocking findings on your change. A periodic checkpoint is a different, persisted report, not delivery sign-off.

   Compare a saved checkpoint →
3. 03

   You authorize persistence

   Check the commit receipt

   What you get

   A commit SHA, explicit changed-file list and fresh local verification results.

   Before moving on

   Keep unrelated work out. A prose verdict or a rendered checkbox does not establish typed-plan acceptance.

   Inspect the commit gate →
4. 04

   You retain merge authority

   Inspect the PR handoff

   What you get

   A PR URL, its current head, verification scope and any unresolved follow-ups.

   Before moving on

   Opening is not merging. Require the applicable exact-head hosted checks and a separate merge decision.

   Inspect PR and cleanup modes →

Reading map, not a captured run or live status. Only the actual artifacts, approvals and fresh checks establish what has completed.

Choose the output you actually need

Your question	Route	What changes or remains
Your question Is this working diff, path or inbound PR ready?	Route review	What changes or remains A local, in-memory verdict. The review itself does not modify files or check out another branch.
Your question What issues need attention across this repository?	Route checkpoint	What changes or remains A dated report under .codearbiter/checkpoints/ and an override-count baseline in .codearbiter/last-checkpoint. Source code stays unchanged.
Your question Do we need a deeper, resumable codebase audit?	Route tribunal	What changes or remains A persisted run under .codearbiter/reports/. It estimates cost and waits for acknowledgement before dispatch. Issue filing and optional KPI submission require their own approvals.
Your question Can this selected work be recorded in Git?	Route commit	What changes or remains A selectively staged commit, after permission and the applicable verification gates.
Your question Can this branch be proposed for integration?	Route pr	What changes or remains Additional required review, then a PR and its handoff. It is not permission to merge.

A periodic checkpoint is not a promotion gate or sign-off. Its last-checkpoint value is an integer override-count baseline, not proof that the commit gate passed. It is also different from the execution checkpoints used to accept a batch of typed-plan work.

For a pre-implementation security analysis, use threat modeling rather than pretending a diff review covers a design that has not been built.

1. Confirm the repository, branch and target

In your native terminal, use these read-only checks:

git rev-parse --show-toplevel
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat

The first two identify the checkout and branch. Status shows changed and untracked paths. The two diff summaries distinguish unstaged and staged changes. An empty summary does not prove there is no work: check both summaries and status. Confirm that your coding host has this same checkout open. Do not switch branches, reset files or discard unrelated work to resemble an example.

For an inbound PR, provide its actual number or URL. The installed route requires authenticated gh; gh auth status checks that prerequisite. A missing CLI, authentication failure or unreadable PR is a stop. It must not fall back to your local diff under the PR’s name.

Host entries

Enter these in your coding host, not in the native shell. Replace 123 with the actual PR number.

Intent	Claude Code	Codex	Pi
Intent Review the current diff	Claude Code /ca:review	Codex $ca-review	Pi /ca-review
Intent Review an inbound PR	Claude Code /ca:review #123	Codex $ca-review #123	Pi /ca-review #123
Intent Save a periodic sweep	Claude Code /ca:checkpoint	Codex $ca-checkpoint	Pi /ca-checkpoint
Intent Commit selected work	Claude Code /ca:commit	Codex $ca-commit	Pi /ca-commit
Intent Open a PR	Claude Code /ca:pr	Codex $ca-pr	Pi /ca-pr
Intent Watch an existing PR	Claude Code /ca:pr --watch 123	Codex $ca-pr --watch 123	Pi /ca-pr --watch 123
Intent Clean up after merge	Claude Code /ca:pr --cleanup	Codex $ca-pr --cleanup	Pi /ca-pr --cleanup

Entry syntax does not establish equivalent host capability. For completed typed HTML work, check the installed host’s authority support first. Current implementation has production verification/review authority on Codex and Claude Code only; Pi lacks the qualified prompt-approval seam. A successful ordinary diff review does not supply those missing capabilities, create an acceptance receipt, or make a draft executable.

2. Read the verdict before requesting a fix

The reviewer fleet is selected by changed paths. Findings are deduplicated and triaged before one read-only verdict is returned. For an inbound PR, the diff is fetched once for the review, so parallel reviewers do not accidentally inspect different revisions.

Check that each material finding identifies a location, the problem, its consequence and a proposed correction. Security findings should name the applicable project control. Resolve numbered [CONFIRM-NN] questions with the actual decision owner rather than letting the agent guess. An out-of-scope [NEEDS-TRIAGE] item is a follow-up to evaluate, not an automatic scope expansion.

For example, a saved-search export review might identify a newline-handling defect:

Illustrative review excerpt, not captured execution:
Target: saved-search CSV change
Finding: a field containing a newline is emitted without CSV quoting.
Consequence: one saved search becomes two records for the receiving application.
Correction: add a regression for the newline field and use the agreed serializer.
Decision: repair this defect within the export change; keep an unrelated UI request separate.

The useful review is specific enough to reproduce. “Improve robustness” alone is not an executable finding. After a correction, rerun the relevant proof and review the changed diff; the old verdict does not automatically cover new code. The first-feature example contains real local test results, separately labelled from its illustrative conversations.

Someone else’s PR: stop here unless asked to post

A local inbound-PR verdict is the deliverable. Do not check out, merge or execute the PR’s code to complete this read-only route. If the author updates the PR after the review, identify the earlier scope and re-review the new diff before presenting the verdict as current.

Posting is a separate, explicit instruction. Inspect the proposed comment before sending it; remove credentials, internal URLs and sensitive repository details. The review route can post a comment after confirmation, but does not issue GitHub Approve or Request changes decisions. Those carry different authority. A CRITICAL or HIGH finding on an inbound PR is reported, not a reason to modify or block unrelated local work.

3. Commit your own change with fresh evidence

Request the smallest correction through the appropriate change lane. For your own work, unresolved CRITICAL or HIGH findings block the PR path. Do not disable a gate to dispose of them.

Before authorizing the commit, inspect the complete staged diff and exact file list. Tests, lint and secret scans come from .codearbiter/tech-stack.md; missing commands must be surfaced, not invented. Run the applicable impact-bounded local verification. Exhaustive repository and platform checks belong to the exact-head hosted-CI merge boundary, not an improvised demand to run every platform locally.

For a typed pair, the installed engine must establish all_accepted_and_current: true for the selected specification and plan, with current acceptance receipts. Neither this guide’s map nor a periodic checkpoint report establishes that result. Stop at unsupported or stale authority and use Resume and recover.

Expected result: the commit receipt gives the SHA, branch, explicit file list, message and fresh gate results. Inspect any remaining uncommitted work rather than calling it clean by assumption. A failed hook is a stop to repair and rerun, not permission to bypass verification.

4. Open the PR and inspect its handoff

The PR path confirms that the commit gate cleared in the current session, then applies its reviewer matrix. A standalone review is useful before this point but is not required as a redundant ceremony. Do not open the PR while a BLOCK-level finding remains.

Read the PR body as a deliverable: what changed and why, how it was tested, what remains, and any applicable decision or tradeoff. Ask for source identities rather than “all green” without a scope. The returned URL proves that a PR exists. It does not prove merge, deployment or publication.

Useful handoff fields: PR URL and base branch; current head SHA; the specification/plan paths when applicable; observed local checks; exact-head hosted checks and their current state; open findings; and the next decision. Omit claimed evidence that was not actually observed.

pr --watch can observe existing checks. Automatic attachment is a separate opt-in setting and must not be enabled on your behalf. On red, inspect the failed job and keep diagnosis separate from authorized remediation. On green, the watcher offers a merge; it does not merge.

5. Merge is a separate decision

Require the repository’s applicable merge-readiness evidence for the PR’s current exact head. A missing, pending, cancelled, stale, mismatched or failing result is not a pass. A newer commit requires current evidence. Impact-skipped checks are not tests that ran.

Under the attended feature path, opening a PR and merging through a PR are distinct choices. Sprint autonomy ends with opening the PR. An owner-authorized merge still goes through the PR and its protection rules. Where ADR lifecycle evidence binds source commits, preserve the merge method selected by the installed verifier; do not casually squash away required ancestry.

A merged PR is still not a release. Follow Release your project for version derivation, dry run and publication permission.

6. Clean up only after proving the work landed

Use pr --cleanup after merge. Expect it to fetch the default branch and establish containment, including the applicable PR-record proof for a squash merge. A gone upstream label alone is not proof. It then classifies leftover work as unique, redundant or superseded and asks about removals individually. Unknown residue remains unique; stashes are reported, not dropped.

Review each named removal and the separate local-branch deletion. Keeping an item or declining deletion is a valid outcome. A branch checked out in another worktree, a divergent local default branch or unproven containment should produce an explanation and stop, not a reset or broad clean. The remote branch is not deleted by this cleanup path.

Expected result: a receipt states what landed, what was kept or removed, and where HEAD now is. A clean exit preserves unrelated work and makes the next repository session understandable.

When the path stops

Observation	Next safe action
Observation Inbound PR cannot be read	Next safe action Restore the CLI/authentication prerequisite or supply an accessible target. Keep the original scope visible.
Observation A verdict concerns the wrong revision	Next safe action Resolve the current target and review that diff again. Do not reuse the old verdict as current proof.
Observation A blocking finding remains on your change	Next safe action Make the bounded correction, rerun its proof, then return through commit and PR review.
Observation Typed authority is missing or stale	Next safe action Use the supported host path and artifact recovery guidance. Do not edit receipts or acceptance labels.
Observation Hosted checks are pending or red	Next safe action Inspect the actual current-head run. Do not substitute a prior green SHA or an unrelated job.
Observation Cleanup would lose unique work	Next safe action Keep or move the named item, or stop cleanup. Do not treat an override as ordinary lifecycle work.

For exact contracts, read review, checkpoint, tribunal, commit, PR, and post-merge cleanup.