PR Review Checklists That Scale With Risk

A useful review checklist changes shape when a pull request touches content, rendering, data contracts, billing, or production operations.

The same pull request checklist cannot cover a typo fix, a homepage redesign, a billing webhook, and a database migration. When the checklist is too generic, reviewers either ignore it or perform ceremony. The better approach is to make the author classify the risk first.

I like a pull request description that starts like this:

Risk area:
- [ ] Content only
- [ ] UI interaction
- [ ] Public API contract
- [ ] Background job
- [ ] Auth or permissions
- [ ] Billing or payment
- [ ] Database migration
- [ ] Infrastructure or deploy behavior

Evidence:
- Build:
- Tests:
- Preview or screenshot:
- Rollback:

The boxes are not bureaucracy. They tell reviewers which questions are worth asking.

Content changes need crawl and preview checks

A content-only PR does not need a concurrency review. It does need a build, a preview URL, frontmatter validation, and link checks. For a static site, the review should open the page, inspect the title and description, and make sure the sitemap or RSS behavior matches the publish intent.

If the post includes images, check the public path and alt text. If it includes future dates, confirm the site treats scheduled content intentionally. Many publishing mistakes are not prose mistakes; they are metadata mistakes.

API changes need replay examples

For an API contract change, ask for one successful payload, one validation error, and one permission failure. The reviewer should not have to infer response shape from implementation code.

Example review evidence:

{
  "request": {
    "method": "POST",
    "path": "/api/exports",
    "body": { "format": "csv", "range": "last_30_days" }
  },
  "response": {
    "id": "exp_732",
    "status": "queued"
  }
}

Then include the conflict or retry case:

{
  "error": {
    "code": "EXPORT_ALREADY_RUNNING",
    "retryable": false,
    "requestId": "req_7z1"
  }
}

That is much easier to review than “added export endpoint.”

Migrations need overlap notes

For database work, the review question is deployment order. Can old code run with the new schema? Can new code run before the backfill finishes? Can workers process both shapes?

A useful migration note is short:

1. Add nullable column `published_at_utc`.
2. Deploy app writing both old and new fields.
3. Backfill existing rows in batches of 500.
4. Switch reads to new field.
5. Remove old field in a later release.

If the PR cannot explain the overlap, it is not ready for a rolling deploy.

Auth changes need ownership language

Permission bugs often hide behind vague wording. Replace “user can access project” with explicit ownership: which user, which account, which workspace, which resource.

Reviewers should look for tests that cross tenants. A passing test where Alice reads Alice’s project is not enough. Add the case where Alice tries to read Bob’s project and receives a denial with a traceable request ID.

The checklist should shrink after low-risk changes

Not every PR needs every section. A copy edit can say:

Risk area: Content only
Evidence: pnpm build, preview opened, links checked
Rollback: revert commit

That is enough. The checklist scales because it asks fewer questions for small changes and sharper questions for dangerous ones.

The review habit to avoid is confidence without evidence. A reviewer cannot inspect everything, but they can ask whether the author supplied the right proof for the kind of risk being shipped.