Give your coding agent a review brief it can use

Prepare a checkable contract.

A useful review brief is short enough to inspect and specific enough to disagree with. It tells the agent what matters about the change without supplying a verdict. Start with one problem and one bounded patch; a broad request to “find all bugs” makes scope and completeness hard to assess.

The brief below is a proposed working format. It is not a special API or a guarantee of review quality. You can paste it into a coding assistant, attach it to a pull request, or use it while reviewing by hand.

Copy this structure.

Leave a field unknown when it is unknown. A short honest brief is more useful than a complete-looking one containing assumptions disguised as requirements.

Problem
- What failure or user need is this change meant to address?

Scope and current state
- What code/version is being reviewed?
- What accepted behavior should remain unchanged?
- Which callers or components are affected?

Constraints and evidence
- State each applicable invariant.
- Link its source and explain why it still applies.
- Mark proposals, historical accounts, and uncertainties explicitly.

Failure cases
- Describe the known incident sequence or plausible boundary case.
- Distinguish observed failures from hypothetical ones.

Verification
- List relevant tests/checks and what each can establish.
- State what remains unchecked.

Review request
- Report actionable findings with location, failure scenario, evidence,
  consequence, and a focused way to verify.
- Ask about missing contracts; do not invent them.

Fill it for a fictional order retry.

The problem is that clients need to retry after losing a response. The current contract says the same request ID represents one accepted creation. The service can accept a request before its response reaches the client. The changed client now retries, but we have not yet established the policy for an ID reused with a different request body.

The review scope is the changed client and the service acceptance path it depends on. Relevant questions include whether attempts reuse the same identifier, whether concurrent matching requests can both create an order, and whether the accepted result can be recovered after the first connection fails.

Ask for findings you can verify.

Have the agent separate a demonstrated defect, a supported concern needing execution, and a missing contract. Each category leads to a different next action. A missing conflict policy may need a decision; a duplicate creation observed in a test needs a fix.

Reject findings that cite a general best practice without connecting it to this implementation and contract. Ask where the failure occurs, what sequence triggers it, and which evidence supports the conclusion. If the source is only a hypothesis, the finding must preserve that status.

Also ask what the reviewer could not inspect. An answer that identifies its boundary is easier to use than one that silently implies complete coverage. Treat confidence words as wording, not verification.

Close the loop with checks.

Run the narrow tests that exercise the suspected behavior. Inspect the test itself: does it recreate the important sequence, and would it fail if the defect returned? A test that waits for a retry without checking the accepted result can miss the actual problem.

After remediation, rereview the changed boundary and record what passed, what was only inspected, and what remains pending. Do not replace a specific test result with “the feature is correct.” Different checks support different conclusions.

Keep the source brief with the change or link it from the review record. Future work should be able to recover the reason a check exists instead of deleting it as an unexplained complication.

Use it where context affects the verdict.

This format is most useful when the review depends on a production exception, an earlier tradeoff, several components, or an ambiguous requirement. For a straightforward local change with an obvious contract, a smaller brief is enough.

For a team pilot, record preparation effort, which findings led to action, important misses, and review rework. Do not count a larger comment list as success. The aim is a review that helps the engineer make the right change with an inspectable basis.