Team PR review automation — evidence before approval
Team PR review automation should make a change easier to judge, not manufacture approvals. A strong workflow runs deterministic checks first, asks an agent to review the accepted intent and risky surfaces, retains reproducible evidence, and routes the result to a named human gate. The right number of AI reviewers is the smallest set that finds useful, non-duplicated issues.
Q9 · Quality gates Max-score evidence: deterministic checks, a focused specification and risk review, reproducible findings, risk-based routing, and a named human merge gate.
Use four review layers
Section titled “Use four review layers”- Prove the mechanical facts. Run formatting, types, unit and integration tests, dependency checks, secret scanning, and any repository-specific policy checks. These are pass/fail evidence, not model opinions.
- Review against accepted intent. Give the reviewer
intent.md,spec.md,plan.md, the diff, and test output. Ask whether the change satisfies the contract and whether the evidence covers the highest-risk behavior. - Route by risk. Authentication, authorization, payments, migrations, public APIs, infrastructure, and sensitive data get specialist review and a stricter human gate. Low-risk documentation or test-only changes can use a lighter path.
- Keep authority explicit. An AI finding may block a check only through a reviewed policy. A named human retains merge authority where repository policy requires judgment.
Claude Code can participate through GitHub Actions, Cursor offers Bugbot, and Codex provides code review. These are implementation options, not proof that three tools are better than one. Measure precision, duplicate findings, escaped defects, queue time, and review effort in your own repositories.
Copy-paste review prompts
Section titled “Copy-paste review prompts”Review this diff against intent.md, spec.md, and plan.md. List only material mismatches. For each finding, cite the file and line, explain impact, and give a reproduction or a missing test. Return "no material finding" when the evidence is sufficient.Inspect only the changed authentication, authorization, data-handling, migration, and rollback paths. Separate verified defects from hypotheses. Do not approve or merge; produce evidence for the named reviewer.Reconcile the deterministic check output and review findings. Deduplicate them, mark each as reproduced, plausible, or unsupported, and identify which repository policy determines whether it blocks merge.Acceptance evidence
Section titled “Acceptance evidence”- Every blocking finding has a reproducer, failing check, or directly cited policy.
- The PR records the accepted intent, systems and data touched, reversibility, commands run, and unresolved risks.
- Risky changes reach the specialist and human gates defined by policy.
- Review metrics distinguish useful findings from noise and track time to accepted change, not comment count.
- A failed or unavailable AI reviewer produces an explicit incomplete-evidence state; it never silently becomes approval.
Failure pattern: reviewer theater
Section titled “Failure pattern: reviewer theater”The workflow fails when teams require several bots on every PR, count comments as coverage, or treat an AI “looks good” message as authority. Reduce overlapping reviewers, make deterministic checks authoritative for mechanical facts, require evidence for model findings, and route judgment to the person accountable for the affected system.
Continue with change controls
Section titled “Continue with change controls”Use Gates vs guardrails to map controls across the lifecycle, then AI in CI/CD to run the bounded server-side loop.