Verification Checklists

Use these as PR comments, issue templates, or a local scratch file. They assume you already know how to test and ship — they encode only what changes when an agent produced the diff. For the reasoning behind each item, see Verification Strategy and Quality Gates.

Before accepting AI-generated code

Run this at the end of an agent session, before you even open a PR.

## Before accepting AI code

- [ ] Task scope: diff touches only files justified by the spec/prompt
- [ ] Agent listed assumptions; each is accepted or corrected in the spec
- [ ] No new dependency without explicit ask + justification
- [ ] No secrets, `.env`, or credentials in the diff
- [ ] Architecture: reuses existing modules; no parallel abstraction
- [ ] Acceptance criteria from the spec are each evidenced (test or manual)
- [ ] Spec-named edge cases appear in tests (grep by name)
- [ ] Tests assert outcomes, not only mock call counts
- [ ] Agent pasted real command output for typecheck/tests/lint — not just "all green"
- [ ] Security-relevant paths (authz, validation, crypto, payments) get a human read
- [ ] Docs touched if behavior user-facing or agent-facing (`CLAUDE.md`, specs)
- [ ] Out-of-scope items from the spec were not "helpfully" implemented

Before merging a PR

## Before merge

- [ ] PR description states intent, spec link, and what was deliberately not done
- [ ] CI green: typecheck, tests, lint, required scans
- [ ] No workflow/threshold/skip changes unless that is the PR's purpose
- [ ] Lockfile diff reviewed if dependencies changed
- [ ] Second-agent or human adversarial review done for money/auth/data paths
- [ ] Behavior review: would a wrong formula / missing authz fail a test?
- [ ] Characterization tests labeled; behavior tests map to spec lines
- [ ] Migrations are backward-compatible or have an explicit expand/contract plan
- [ ] Feature flags / config defaults are safe if rolled out dark
- [ ] Rollback path named (revert PR, flag off, or forward fix)
- [ ] Preview/smoke checked for user-facing changes
- [ ] Reviewer did not share the builder's chat context as the review brief

Before deploying

## Before deploy

- [ ] Merge commit is the one you reviewed (no late agent force-pushes unread)
- [ ] Release notes / changelog mention user-visible and ops-visible changes
- [ ] Migrations run plan: order, lock risk, estimated duration, who watches
- [ ] Alerts/dashboards exist for new failure modes (or explicitly deferred)
- [ ] Config/env vars present in target environment; no reliance on local `.env`
- [ ] Smoke script or checklist ready for the critical paths this touches
- [ ] On-call knows the change window and rollback command
- [ ] Performance budget unchanged unless this release intentionally moves it
- [ ] Security findings from CI triaged — no "fix later" on high severity

After deploying

## After deploy

- [ ] Smoke: login / critical write path / critical read path as applicable
- [ ] Error rate, latency, and saturation within normal band for 15–30 min
- [ ] New logs/metrics from the change are arriving (not silent)
- [ ] Migration finished; no long-running locks; row counts sane if relevant
- [ ] Support/queue: no spike in related tickets or user reports
- [ ] Feature flag percentage matches intent
- [ ] If anything anomalous: roll back or flag off first, debug second
- [ ] Update runbook/`CLAUDE.md`/spec if production revealed a missing invariant

When a bug is found

Whether the bug is in agent-written code or not, the agent will pattern-match a fix. Force evidence and a regression test so you do not get a stuck loop or a silent edge-case deletion.

## When a bug is found

- [ ] Reproduce with a minimal failing case (script, test, or recorded request)
- [ ] Capture evidence: logs, metrics, request IDs, screenshots — before prompting
- [ ] Write or demand a regression test that fails on main and passes on the fix
- [ ] Agent prompt includes: reproduce → hypothesize → fix; no fix before repro
- [ ] Diff reviewed for unrelated "while I was here" changes
- [ ] Check the agent did not delete/skip the failing assertion to go green
- [ ] Check related edge cases still present (agents "simplify" under pressure)
- [ ] Spec/invariant updated if the bug revealed undocumented rules
- [ ] Postmortem note if production impact: what gate should have caught this?
- [ ] Fresh session if the debugging chat is defending a refuted hypothesis

How to use these without ceremony

• Paste the relevant block into the PR as a checklist comment on agent-heavy changes.
• For juniors supervising agents, require the "before accepting" list before they request review.
• For incidents, the "when a bug is found" list is the prompt scaffold — fill evidence first, then open Claude Code.
• Broader template variants live under Templates: Checklists when that section is present; these five are the verification-critical core.

Related

• Verification Strategy — the pipeline these lists operationalize.
• Quality Gates — automated gates referenced by the merge/deploy lists.
• Reviewing AI Tests — deep dive on the test-specific items.
• Reviewing AI PRs — human review passes that pair with "before merge."
• Recovering From Bad Output — when accepting was a mistake.
• Production Debugging — expand the bug-found checklist into a full playbook.