Security-Sensitive PR Review Card

This card structures a PR review. It does not approve a change, certify it safe, or replace an audit. AI may summarize the diff and draft the first pass; a named human decides whether the PR can merge. Completing the card does not mean the change is safe or audited — it means the review happened on the record.

What this card does

It turns a risky PR into a structured, reviewable artifact: what changed, whether it touches audited assumptions, what test evidence backs it, and which named human has to sign off before merge.

When to use it

Open a card on any PR that touches:

• Audited code (any file inside the audited commit's scope).
• Privileged roles or access control — admin, guardian, owner, pauser, multisig threshold.
• Oracles or pricing — feeds, heartbeats, staleness/deviation bounds, fallback sources.
• Upgrades, proxies, or storage layout.
• External calls or integrations — new protocols, approvals, dependency migrations.
• Economic parameters — shares, fees, caps, interest, rewards, liquidation logic.
• New dependencies or a compiler/optimizer bump.
• Deployment or config — new chain, new implementation, changed deploy script.
• Invariants or test weakening — assertions loosened, tests skipped, coverage dropped.
• Audit-finding fixes — code that closes a reported issue.
• AI-generated code in any sensitive path above.

If a PR touches none of these, you probably do not need a card. If you are unsure, open one.

How to use it

Card template

The full blank card is in the panel — use Copy template or Download .md (Blank PR review card) and drop it straight into your PR body or post it as the first review comment. One card per PR. It captures the change summary, risk indicators, audit relevance, test evidence, required reviewers, the AI boundary, and the human decision.

Risk indicator taxonomy

Tag every indicator the diff touches. Each carries a default escalation — the floor for that surface, not the ceiling.

Risk level rubric

Score the worst applicable indicator; when unsure, round up. Risk is always labeled by name, never by color alone.

Audit-relevance call-out. If the PR changes audited code or contradicts a stated audit assumption, it is High at minimum — regardless of diff size. A one-line change can invalidate an assumption.

Drift-relevance call-out. If the change drifts the live system away from the audited snapshot, link it to an Audit Drift Checklist item (AD-NNN) so release-level review can pick it up. PR review and drift review share one register.

Evidence required before merge

A checked box without a link is not evidence. Every claim on the card points to something a reviewer can open: a test file/line, a CI run, a tx hash, a config dump, or the relevant audit-report section.

Evidence types: unit tests, fork/integration tests, invariant/fuzz tests, a green CI run, on-chain proof (address / tx hash), config dump, and the audit-section reference.

The rule, stated once: a checked box without a link is not evidence.

What AI must not decide

The boundary is the whole point. AI accelerates the review; it does not own the call.

AI may:

• Summarize the diff and list the changed files.
• Propose which risk indicators the change touches.
• Draft the risk card as a first pass.
• Flag missing tests, missing evidence, and open questions.
• Suggest questions for the human reviewer to ask.

AI must not:

• Approve the PR or mark it "ready to merge."
• Declare the change safe or audited.
• Decide whether an invariant holds.
• Decide whether an audited assumption still holds.
• Replace a named human signoff.

Paste only code you are allowed to share with a model — never private keys, secrets, or proprietary code outside your policy.

You are drafting a Security-Sensitive PR Review Card for a smart contract pull request.
 
INPUT: the PR diff, changed file list, PR description, and any linked tests.
 
DO:
1. Write a one-line plain-English summary of what the change does and its blast radius.
2. Classify the change against this risk-indicator taxonomy and tag every indicator it touches:
   Access control / roles; Upgradeability / proxy / storage layout; Oracle / pricing;
   External integrations; Economic logic; Accounting / invariant; Deployment / config;
   Governance / timelock; Dependencies / compiler; AI-generated code; Audit-finding fix;
   Test weakening.
3. Assign a tentative risk level by NAME — Low / Medium / High / Blocked — and state why.
4. List the test evidence present, and explicitly flag missing evidence:
   missing fork tests, missing failure-mode tests, weakened assertions, skipped tests,
   dropped coverage.
5. List open questions and unknowns the human reviewer must resolve.
6. Suggest specific questions for the reviewer to ask the author.
 
DO NOT (these require a named human, never the model):
- Do NOT approve the PR or say it is "ready to merge."
- Do NOT declare the change safe, correct, or audited.
- Do NOT decide whether any invariant holds.
- Do NOT decide whether an audited assumption still holds.
- Do NOT replace human signoff.
Where any of these would be required, write: "Human decision required" and stop.
 
OUTPUT: the filled markdown review card, with every unknown and missing piece of
evidence clearly marked. End with a "Human decision required" line — do not fill it in.

Human decision

Tooling structures the decision; a human makes it. Every Medium-and-above card needs a named person — not a role — on the record before merge.

Fields: owner (named human), decision, date, rationale, linked evidence, and any conditions. Decision options:

• Proceed — within known/audited intent; evidence is complete.
• Proceed with conditions — merge allowed once named conditions are met (e.g., a follow-up test lands).
• Block — do not merge until resolved.
• Escalate to senior review — route to a named senior/security engineer.
• Escalate to external review — route to an external auditor for the changed surface.
• More information required — author must supply named evidence before a decision.

No Proceed is permitted while a required test or the audit-relevance signoff is missing.

Filled example

A worked example on a fictional protocol — DroidVault, an ERC-4626 yield vault with upgradeable contracts, oracle-based pricing, a 3-of-5 multisig admin behind a 48-hour timelock, and a RewardsDistributor. The prior audit (Example Security Labs, 2026-03-15, commit abc1234, Ethereum mainnet) recorded a single primary oracle with no fallback path — Chainlink ETH/USD as the sole price source, with a 1-hour staleness check.

PR #184 — "Add fallback oracle to DroidVault pricing adapter." It adds a FallbackOracleAdapter, modifies OracleAdapter, adds one config value (the fallback feed address), updates the deployment config, and adds unit tests.

Audit relevance: High. The change contradicts a stated audit assumption — Chainlink is no longer the sole price source. That alone floors this at High.

Missing evidence: no fork tests; no decimal-normalization test for the fallback feed; no stale/failed-fallback behavior test. The unit tests do not prove the failure modes the audit assumption protected.

Decision: Block. Do not merge until (1) the missing tests land — fork tests, decimal normalization, and stale/failed fallback behavior; (2) the fallback trust assumption is documented; and (3) a named senior reviewer signs off. Maps to drift item AD-002 (fallback oracle added). Decision owner: Alex Reviewer (Security).

Download the full worked example from the panel (Filled DroidVault example) to see the complete card — change summary, every indicator, the evidence log with the gaps named, and the Block decision filled in end to end.

GitHub-ready usage

Drop the GitHub PR template from the panel into .github/PULL_REQUEST_TEMPLATE/ so every security-sensitive PR opens with the card pre-filled. Wire the rest of the workflow with native GitHub:

• Labels — add a security-sensitive label that triggers required review.
• CODEOWNERS — route sensitive paths (oracle, proxy, access-control, deploy) to named security reviewers automatically.
• Branch protection — require the security reviewer's approval and a green CI run before merge on protected branches.

The GitHub Actions plan download wires it into CI: detect touched sensitive paths, post the card scaffold as a PR comment, and gate merge on the named human decision. The card stays the source of truth; CI just enforces that it gets filled and signed.

Related resources

• Audit Drift Checklist — the release-level companion; this card is the per-PR version of the same register.
• AI Agent Permission Boundary Checklist — the permission-boundary companion for AI agents with repo access.
• Drift Was Audited. That Was Never the Point. — the why behind both.
• The Release Review — senior review of the PRs this card flags, against your audited baseline.

Version history