tomevault-io Spec Quality Checklist
Validate a specification for precision and completeness before implementation.
When to Use
- After drafting a spec with
brainstormingskill - Before creating an implementation plan
- When reviewing an existing spec for gaps
How to Use
Announce: "I'm using the spec-quality-checklist skill to validate this spec." This runs in a forked spec-reviewer agent context.
Create TodoWrite items for each section below. Mark items as you verify them.
Precision Requirements
Check that boundaries are testable, not vague:
| Requirement | Bad (Ambiguous) | Good (Testable) |
|---|---|---|
| Boundaries | "green for low values" | "green when value < 3.5" |
| Types | "returns user data" | "returns { id: string, name: string, email: string }" |
| Error handling | "handle errors gracefully" | "show toast on failure, log to console in dev only" |
| Accessibility | "make it accessible" | "arrow keys increment/decrement, changes announced to screen readers" |
| States | "show loading state" | "skeleton loader matching final layout dimensions while fetching" |
| Timing | "should be fast" | "response within 200ms at p95" |
| Validation | "validate the input" | "email must match RFC 5322, show inline error on blur" |
| Permissions | "admins can edit" | "users with role='admin' see Edit button, others see read-only view" |
Completeness Checklist
Create TodoWrite items for each:
User Stories
- All user types identified (admin, member, guest, etc.)
- Each user type has clear capabilities defined
- Edge user states covered (new user, returning user, user with no data)
Data Model
- All entities have explicit field names and types
- Relationships are defined (one-to-many, many-to-many)
- Constraints are specified (required, unique, max length)
- Default values are defined where applicable
API Contracts
- All endpoints have request/response shapes
- Error responses are defined with status codes
- Authentication/authorization requirements are clear
- Rate limiting or pagination specified if relevant
UI/UX
- All screens/components are listed
- All states are defined: loading, empty, error, success
- Interaction patterns are explicit (click, hover, drag, keyboard)
- Responsive behavior is specified if relevant
Acceptance Criteria
- Each criterion is independently testable
- Success and failure conditions are explicit
- No criterion uses subjective language ("looks good", "feels fast")
Red Flags
Stop and clarify if you see:
- "etc." or "and so on" — enumerate the full list
- "appropriate" or "suitable" — define specifically what qualifies
- "user-friendly" or "intuitive" — describe the exact behavior
- "handle edge cases" — list the specific edge cases
- "similar to X" — specify the exact aspects to replicate
- Missing error scenarios — every happy path needs a sad path
Workflow
- Read the spec thoroughly
- Create TodoWrite with all checklist items
- Work through each item, marking complete or noting gaps
- For any gaps found, either:
- Fix them in the spec immediately, or
- Document them for discussion with the user
- Report: gaps found, gaps fixed, items needing clarification
Output
After validation, provide:
- Verdict: approve / revise
- Gaps fixed: List of issues you corrected
- Needs clarification: Items requiring user input
- Red flags: Any vague language that should be made precise
Converted and distributed by TomeVault — claim your Tome and manage your conversions.