spec-validation
Validates specification quality for technology-agnosticism, testability, and completeness. Automatically invoked when reviewing specs, checking requirements, or before transitioning from specify to plan phase.
When & Why to Use This Skill
The Spec Validation skill is an automated quality assurance tool designed to audit technical specifications for clarity, testability, and completeness. It optimizes the software development lifecycle (SDLC) by enforcing technology-agnostic descriptions and measurable requirements, ensuring that project documentation is robust enough to guide development without premature implementation bias or ambiguous goals.
Use Cases
- Requirement Auditing: Automatically review spec.md files to identify and replace vague language like 'fast' or 'intuitive' with measurable performance metrics and verifiable criteria.
- Technology Decoupling: Scan specifications for specific frameworks, libraries, or database references to ensure business logic remains independent of the underlying tech stack.
- Edge Case Discovery: Analyze project scopes to detect missing error handling, empty states, or boundary conditions before moving from the specification phase to technical planning.
- Workflow Gatekeeping: Serve as a mandatory quality gate to ensure specifications meet high standards of consistency and completeness before developers begin the implementation phase.
| name | spec-validation |
|---|---|
| description | Validates specification quality for technology-agnosticism, testability, and completeness. Automatically invoked when reviewing specs, checking requirements, or before transitioning from specify to plan phase. |
Spec Validation Skill
You are validating specifications in a Spec Kit workflow. This skill ensures specifications meet quality standards before proceeding to technical planning.
Validation Criteria
1. Technology Agnosticism
Specifications must describe WHAT and WHY, not HOW. Flag any references to:
Frameworks & Libraries
- ❌ React, Vue, Angular, Django, FastAPI, Express
- ❌ Redux, MobX, Zustand (state management)
- ❌ Tailwind, Bootstrap, Material UI (styling)
Languages & Syntax
- ❌ async/await, promises, callbacks
- ❌ decorators, hooks, mixins
- ❌ specific type systems
Databases & Storage
- ❌ PostgreSQL, MongoDB, Redis, S3
- ❌ SQL queries, NoSQL patterns
- ❌ Specific ORM syntax
Infrastructure
- ❌ Docker, Kubernetes, AWS, GCP
- ❌ Specific API protocols (REST, GraphQL, gRPC)
- ❌ Deployment patterns
Good Example:
Users can view their order history sorted by date.
Bad Example:
Use React Query to fetch orders from the REST API and display in a Tailwind-styled table.
2. Testability
Every requirement must be verifiable. Flag:
Vague Requirements
- ❌ "System should be fast"
- ❌ "Good user experience"
- ❌ "Intuitive interface"
- ❌ "Improve performance"
Subjective Criteria
- ❌ "Easy to use"
- ❌ "Modern design"
- ❌ "Scalable architecture"
Good Examples:
- Page loads in under 2 seconds on 3G connection
- Form validates email format before submission
- Users receive confirmation within 24 hours
- System handles 1000 concurrent users
3. Completeness
Check for:
Missing Scenarios
- Happy path (main flow)
- Error cases (what can go wrong)
- Edge cases (boundary conditions)
- Empty/null states
Undefined Terms
- Acronyms without definitions
- Domain-specific terms
- Ambiguous references ("the system", "it")
Missing Acceptance Criteria
- Success conditions
- Error conditions
- Performance requirements
- Security requirements
4. Consistency
Verify:
- No contradicting requirements
- Consistent terminology
- Aligned with constitution (if exists)
- No duplicate requirements
Output Format
When validating, produce:
## Spec Validation Report
### Summary
| Criterion | Status |
|-----------|--------|
| Technology Agnosticism | ✅ PASS / ⚠️ ISSUES |
| Testability | ✅ PASS / ⚠️ ISSUES |
| Completeness | ✅ PASS / ⚠️ ISSUES |
| Consistency | ✅ PASS / ⚠️ ISSUES |
### Issues Found
#### Technology Leaks
- Line 42: "Use PostgreSQL for storage" → Rephrase as "Data persists across sessions"
#### Testability Issues
- Line 15: "System should be intuitive" → Add measurable criteria
#### Missing Scenarios
- No error handling for invalid input
- No empty state defined
### Recommendations
1. [Priority 1] Remove database reference on line 42
2. [Priority 2] Add success criteria for requirement 3
3. [Priority 3] Define acronym "SSO" on first use
When to Invoke This Skill
Claude should use this skill when:
- User creates or edits a spec.md file
- Before running
/speckit.plan - User asks to review a specification
- Discussing requirement quality
- Transitioning from specify to plan phase
Validation Process
- Read the spec.md file
- Check each section against criteria
- Note specific line numbers for issues
- Prioritize findings by impact
- Suggest concrete improvements
Integration with Workflow
specify → [VALIDATION] → clarify → plan
↑
This skill
After validation:
- If PASS: Proceed to
/speckit.plan - If ISSUES: Run
/speckit.clarifyto resolve - If MAJOR ISSUES: Revise spec before proceeding