When to use this checklist
Use this review after the first complete draft and before implementation starts. A spec review is not a writing-quality pass. It is a risk pass: can an implementer identify the current behavior, the required change, the forbidden adjacent work, the edge cases, and the verification path?
For a mechanical first pass, run the draft through the Ambiguity Checker. For a missing-structure pass, rebuild the draft with the Spec Builder or compare it against the technical spec templates.
1. Current behavior is specific
The spec should say what happens today before it says what should change. Look for named modules, routes, jobs, data stores, UI states, permissions, or tests. If the current behavior is only "this is confusing," the implementer will have to rediscover the system boundary during implementation.
2. Goal is observable
The goal should describe the intended system or user outcome without hiding inside a solution word. "Make onboarding better" is not observable. "Block workspace creation until the signup email is verified" is observable and reviewable.
3. Non-goals are concrete
Non-goals should name the work that is tempting but out of scope. "Do not change billing-plan calculation" is stronger than "avoid unrelated changes." This is especially important for AI-executable specs, where scope fences tell the agent where to stop.
4. Requirements are individually testable
Each requirement should express one obligation. If a requirement has several verbs, split it. If it uses MUST, SHOULD, or MAY, make sure the meaning is consistent with the team's requirement language and that each MUST maps to acceptance or verification.
5. Acceptance examples cover edge cases
Happy-path examples are not enough. Ask whether the spec covers empty states, invalid input, unauthorized users, retries, duplicate requests, stale data, dependency failures, and migration overlap. Given/When/Then examples help because they force the review to name state, action, and result.
6. Verification commands are named
"Test manually" is not a verification plan. Name the exact unit tests, build commands, browser flows, API calls, migration checks, telemetry events, or logs that prove the change. If automation is not practical, the manual check should still be specific enough for another reviewer to repeat.
7. Rollout and migration risk are visible
Any change touching persisted data, permissions, notifications, billing, integrations, analytics, or search indexes needs rollout notes. Review migration order, read/write compatibility, rollback, support visibility, and what happens while old and new states coexist.
8. Agent handoff has scope fences
If a coding agent will implement the spec, the final handoff should include working directory, read-first files, allowed edit surfaces, non-goals, examples, done criteria, stop conditions, and final-report expectations. OpenAI's AGENTS.md guidance is useful for standing repo instructions; this checklist focuses on task-specific decisions.
Copy-ready review prompt
Review this technical spec before implementation.
Check for:
- missing current behavior
- vague goals or requirements
- non-goals that do not fence scope
- requirements without acceptance criteria
- missing edge cases
- verification that cannot be repeated
- rollout or migration risks
- missing AI-agent handoff constraints
Return blocking issues first, then non-blocking improvements.