Checklist Templates

Human gates. Run these yourself — do not ask the agent to "self-certify" and move on. Pair with Verification Checklists and Reviewing AI PRs.

Code review checklist

Use on every PR. Tool-agnostic; still apply when a human wrote the diff.

# Code review — <PR title / number>

Reviewer: `<name>` · Author: `<human | agent + human>` · Spec: `<link or n/a>`

## Scope
- [ ] Diff matches the stated intent / spec (no drive-by refactors)
- [ ] Blast radius acceptable; unrelated files untouched
- [ ] Public API / schema changes are intentional and documented

## Correctness
- [ ] Edge cases and failure paths handled (not only happy path)
- [ ] Error handling doesn't swallow or mis-classify failures
- [ ] Concurrency / idempotency considered where relevant

## Design
- [ ] Fits existing architecture / ADRs (no new layer invented casually)
- [ ] No duplicated utility that already exists in the repo
- [ ] Complexity justified; simpler alternative considered

## Tests & ops
- [ ] Tests assert behavior, not implementation trivia
- [ ] Observability: logs/metrics/traces adequate for this change
- [ ] Migrations / feature flags / rollback path clear

## Verdict
- [ ] Approve
- [ ] Request changes — notes: `<…>`

AI-generated PR checklist

Use in addition to the code review checklist when an agent authored most of the diff. Agents optimize for plausible completeness, not truth.

# AI PR review — <PR title / number>

Spec / prompt: `<link>` · Model / tool: `<…>` · Session notes: `<link or n/a>`

## Spec fidelity
- [ ] Every acceptance criterion is met or explicitly deferred
- [ ] No extra features, files, or abstractions beyond the ask
- [ ] "Done" claims match runnable verification (not narrative)

## Trust but verify
- [ ] Spot-check claims in comments / PR description against code
- [ ] Search for hallucinated imports, APIs, config keys, and paths
- [ ] Generated tests fail on main without the fix / feature (where applicable)

## Architecture & debt
- [ ] No new patterns that fight ARCHITECTURE.md / ADRs
- [ ] No copy-paste modules that should have reused existing code
- [ ] Secrets, credentials, and PII absent from diff and logs

## Process
- [ ] CLAUDE.md / TASKS.md / changelog updated if required
- [ ] Human owns merge decision; agent did not "approve" itself

## Verdict
- [ ] Safe to merge after human approval
- [ ] Revert / recover — see [Recovery](/workflows/recovery)

Deployment checklist

Use before promoting to staging or production. Fill env-specific rows; don't skip rollback.

# Deployment — <service / version> → `<env>`

Deployer: `<name>` · Window: `<time>` · Change ticket: `<…>`

## Pre-deploy
- [ ] Spec / release notes reviewed; known risks listed
- [ ] CI green on the exact commit being deployed
- [ ] Migrations reviewed (expand/contract); backward compatible if needed
- [ ] Feature flags / config defaults set
- [ ] Rollback procedure rehearsed or documented for this change
- [ ] On-call aware; comms channel ready

## Deploy
- [ ] Deploy executed via `<approved path — not ad-hoc scripts>`
- [ ] Migrations applied successfully
- [ ] Smoke checks: `<list URLs / commands>`
- [ ] Error rate / latency within budget for `<N minutes>`

## Post-deploy
- [ ] Monitor dashboards / alerts for `<duration>`
- [ ] Customer-facing notes published if needed
- [ ] TASKS / release record updated

## Abort criteria
If `<metric / symptom>`, rollback via `<procedure>`.

Security review checklist

Use for auth, tenancy, payments, file upload, admin, or any new trust-boundary crossing. Not a substitute for a dedicated security review on high-risk systems.

# Security review — <change title>

Reviewer: `<name>` · Threat notes: `docs/SECURITY.md` · Related ADR: `<…>`

## AuthN / AuthZ
- [ ] Authentication required where expected; no accidental public routes
- [ ] Authorization checked server-side (not UI-only)
- [ ] Tenancy / object-level access enforced on every data path

## Data & secrets
- [ ] No secrets in code, logs, client bundles, or PR text
- [ ] PII minimized; retention / redaction considered
- [ ] Encryption / hashing choices match existing standards

## Injection & abuse
- [ ] Input validation at trust boundaries
- [ ] SQL / command / template injection surfaces reviewed
- [ ] SSRF / open redirect / path traversal considered for fetches & uploads
- [ ] Rate limiting / abuse controls adequate for new endpoints

## Dependencies & supply chain
- [ ] New dependencies justified; known CVEs checked
- [ ] Generated or vendored code reviewed at the same bar

## Verdict
- [ ] Accept
- [ ] Accept with follow-ups: `<…>`
- [ ] Block — issues: `<…>`

Testing plan

Use before implementation or as the verify section of a spec. Forces what "done" means beyond "tests were added."

# Testing plan — <feature / bug>

Spec: `<link>` · Owner: `<name>`

## Risks to cover
| Risk | How we will catch it | Suite |
|---|---|---|
| `<wrong authz>` | `<test or manual>` | `<unit / int / e2e>` |
| `<…>` | `<…>` | `<…>` |

## Automated
- [ ] Unit: `<behaviors>`
- [ ] Integration: `<behaviors + services needed>`
- [ ] E2E / smoke: `<critical path>`
- [ ] Regression for bugfixes: fails without fix

## Manual / exploratory
- [ ] `<scenario>`
- [ ] `<scenario>`

## Out of scope this change
- `<what we are explicitly not testing and why>`

## Exit criteria
- [ ] All checklist items above green on CI for this commit
- [ ] No known Sev-1/2 gaps deferred without owner + date

Production readiness review

Use before first production cut of a service or a major subsystem. Broader than a single deploy checklist.

# Production readiness — <system / milestone>

Owner: `<name>` · Reviewers: `<names>` · Target date: `<…>`

## Product & scope
- [ ] MVP / feature acceptance criteria met
- [ ] Explicit non-goals still hold (no silent scope creep in prod)

## Reliability
- [ ] SLOs defined: availability / latency / error rate
- [ ] Alerting covers those SLOs; pages go to a human
- [ ] Runbooks for top failure modes exist
- [ ] Backup / restore or data durability story documented

## Security & compliance
- [ ] Security checklist completed for in-scope surfaces
- [ ] Secrets management and rotation path clear
- [ ] Audit / access logging adequate for the domain

## Operability
- [ ] Deploy + rollback proven in staging
- [ ] Migrations strategy safe for production traffic
- [ ] Dashboards and structured logs in place
- [ ] On-call rotation and escalation defined

## Agent / process
- [ ] CLAUDE.md / ARCHITECTURE / DEPLOYMENT docs reflect reality
- [ ] Known agent failure modes for this system documented

## Go / no-go
- [ ] Go
- [ ] No-go — blockers: `<…>`

Related

• Verification Checklists — deeper verify procedures
• Reviewing AI PRs — playbook for agent diffs
• Quality Gates — CI gates that back these lists
• Verification Strategy — what humans must own
• Templates index