Review an AI-generated PR

You'll end up reviewing from the reasoning record instead of squinting at an 800-line diff — checking the handful of claims that matter and the gaps the author declared, and skipping the noise.

1. Open the record, not the diff

If the repo runs the pr-trace action, the PR already has a comment with the grade, the declared gaps, and a one-click viewer. Otherwise, open the trace that ships with the change:

ponens trace view trace.json                   # opens the interactive viewer
ponens trace view trace.json --out review.html # or write the HTML (e.g. a CI artifact)

The viewer zooms from intent-named steps down to atomic actions, with the lineage DAG, the decisions, and the residual surface. See it live in the demo.

2. Start from the residual surface

The fastest signal in the whole record: what the change did not establish — assumptions, unverified claims, out-of-scope items. It tells you where to look.

ponens trace residuals trace.json

Triage these first. A high-severity assumption or an unverified claim on a consequential path is exactly where your attention is worth the most.

3. Verify the claims that matter

For each consequential claim, check the evidence the record points to — the test result, the proof, the verification artifact — rather than re-reading every line. Trust reproduction and the atomic actions; treat the curated narrative as a map, not proof.

ponens trace check trace.json                  # did Computable Governance pass?
ponens trace reproduce trace.json              # does it rebuild from the recorded inputs?

4. Hunt the undeclared gaps

The residual surface lists what the author knew they didn't establish. Your job is the gaps they didn't declare — a claim with no artifact behind it, a high-stakes edit with no verification in its lineage. Record what you find as review items:

ponens trace comments add trace.json --on m3 --body "What about partial refunds?"
ponens trace review-items add trace.json --severity high --statement "…"

5. Sign off

Approve when the consequential claims hold and the declared gaps are acceptable — or request changes with specifics tied to a step. The reasoning stays bound 1:1 to the commit, so the record of how the code came to be is auditable later.

ponens trace approve trace.json                # or: review-items / request changes

See the full protocol in the Review handoff spec →