Topics / Engineering practice
Review the change, not just the diff.
A pull request needs a clear account of intended behavior, affected promises, current evidence and unresolved decisions. Code inspection is one part of that account.
Give the reviewer something to decide.
A file diff is precise about edited text. It is less helpful about why a behavior exists or whether a neighboring promise still holds. Put those facts next to the change, with links to the source of each claim.
| Review question | Useful artifact |
|---|---|
| What behavior changes? | Approved requirement delta and preserved behavior |
| What else could be affected? | Traced requirements and dependencies, with mapping limits |
| What supports the claim? | Executed checks on the reviewed revision |
| What remains open? | Failures, missing evidence, exceptions and their owners |
Make a hidden contract change obvious.
Illustrative example
A serializer omits a field older clients expect.
A one-line change omits empty values from an API response. The agreed contract requires completed_at to be present, with null while work is pending. Current server tests accept either shape, but a supported client requires the field. The review needs the published response contract, supported-client expectations and a check of the pending response.
Retain the field when compatibility is required. If the team intends to change the contract, expose that amendment and its client migration decision in the PR. A passing test that accepts both shapes does not establish compatibility with the stricter client.
Put a short decision record in the PR
For the serializer example, a useful review record could look like this. It is illustrative; the response assertion is the evidence to request, not a result already observed.
Change: omit empty response fields.
Must preserve: supported clients receive completed_at: null while pending.
Reach: serializer, pending-response contract, supported client parsers.
Existing tests: accept either an absent field or null; insufficient for this claim.
Required check: assert the field is present and null in a pending response.
Evidence: not run; attach revision, inputs and output after execution.
Decision: preserve the field, or authorize a contract and migration change.
Decision owner: the role responsible for the supported-client contract.Once the check runs, replace “not run” with its observed outcome and artifact. Keep unrelated passing tests out of the summary unless they support a material preserved behavior. The reviewer should be able to find both the result and the remaining decision without reading an agent transcript.
Generate a starting brief with Proof.
The CLI builds a deterministic brief from changed requirements and their recorded graph connections. It helps assemble context; it does not perform an AI semantic code review or execute every linked check.
proof review-pr --base main --format commentFor a code-only PR, the default brief may report no changed requirements. Use --req with the relevant requirement IDs and inspect the code and execution evidence separately. Unmapped code or incomplete links can leave gaps. Keep required code review, independent verification and acceptance authority in the project policy rather than assuming a generated brief grants permission to merge.
Try it on your software
Bring a PR that takes too long to review.
We will build the evidence view around the questions your reviewer actually asks.