Review an AI-generated PR

You'll end up reviewing against a goal contract instead of squinting at an 800-line diff — confirming the goal was met and governed, then certifying the criteria were the right ones. Certified is the reviewer's axis: the doer can produce met and governed, but only a non-doer can certify.

1. Open the record, not the diff

If the repo runs the pr-trace action, the PR already has a comment with the goal's met / governed / certified status 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. Check the contract verdicts

Start where the record already renders judgment. Met tells you the acceptance criteria resolved from real evidence; governed tells you the rigor-bar policies held:

ponens trace goal ls trace.json                # per goal: met + faithfulness
ponens trace enrich trace.json                 # met ∧ governed ∧ certified, with resolved evidence
ponens trace check trace.json                  # the governed axis, on its own

Each met criterion points at the artifact that satisfies it — a proof, a decomposition, a test suite — resolved by lineage, so "done" means the evidence traces back to the code component, not that a sentence sounded right.

3. Read the negative space

The residual surface is what the change did not establish — assumptions, unverified claims, out-of-scope items the author declared. It tells you where a green contract still leaves risk.

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.

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 met-looking criterion whose evidence doesn't actually trace back, a high-stakes edit with no verification in its lineage. Record what you find so it stays on the record:

ponens trace residual add trace.json \
  --kind unverified --severity high \
  --statement "Partial refunds have no verification in lineage" \
  --target-type artifact --target-id vg2

(When the trace lives on the Hub, the same findings can go up as ponens review-items add and ponens comments add.)

5. Certify — the reviewer's sign-off

When the consequential claims hold and the declared gaps are acceptable, certify that the definition of done was the right one — or request changes with specifics tied to a step. This is a distinct axis from met and governed, and it can only come from someone who didn't do the work.

ponens trace goal certify trace.json --by reviewer --verdict approved
ponens trace goal certify trace.json --by reviewer --verdict changes-requested --note "…"

The reasoning stays bound 1:1 to the commit, so the record of how the code came to be — and that a human vouched for the bar — is auditable later.

See the full protocol in the Review handoff spec →