Spec Validation
Systematic quality validation for specifications using structured checklists and self-evaluation patterns.
When to Use
- After drafting *_FEATURE.md specifications
- Reviewing PRDs for completeness
- Validating requirements before handoff
- Self-checking document quality
Core Principle
The best form of feedback is clearly defined rules, then explaining which rules failed and why.
Validation Framework
1. Completeness Check
| Section |
Required Elements |
Validation Question |
| Problem |
Specific pain point |
Is the problem measurable, not vague? |
| Users |
Primary + secondary |
Are personas defined with proficiency? |
| Scope |
In-scope + non-goals |
Are explicit exclusions documented? |
| Success |
Quantified metrics |
Can we measure success after 30 days? |
| Risks |
Scenarios + mitigations |
Is worst-case documented with exit strategy? |
2. Clarity Check
| Criterion |
Test |
Fix |
| No TBD/TODO |
Search for "TBD", "TODO", "??", "TBC" |
Resolve or escalate |
| Acronyms defined |
All acronyms in glossary |
Add definitions |
| Edge cases covered |
Each use case has edge cases |
Document behavior |
| Error messages actionable |
User can self-resolve at 3 AM |
Add context/guidance |
3. Consistency Check
| Check |
Method |
Resolution |
| Policy contradictions |
Compare rules pairwise |
Document precedence |
| Trade-off conflicts |
Map priority vs constraint |
Make explicit choice |
| Priority ambiguity |
Count must-have items |
Limit to 3-5 MVP items |
4. Feasibility Check
| Aspect |
Validation |
Owner |
| Technical constraints |
Engineering review |
Tech Lead |
| Dependencies |
Identify external blockers |
PM |
| Timeline |
Scope vs deadline match |
PM + Eng |
| Risks |
Mitigation plans exist |
PM |
Self-Evaluation Pattern
Use mcp__sequential-thinking__sequentialthinking for systematic review:
# Structured self-evaluation
mcp__sequential-thinking__sequentialthinking(
thought="Reviewing spec for completeness: checking problem statement",
thoughtNumber=1,
totalThoughts=5,
nextThoughtNeeded=True
)
Sequential Review Steps
- Problem Clarity: Is the root problem specific and measurable?
- User Definition: Are primary users and stakeholders identified?
- Scope Boundaries: Are in-scope and non-goals explicit?
- Success Criteria: Can we objectively measure success?
- Risk Coverage: Are failure scenarios and rollback documented?
Validation Report Template
## Spec Validation Report: {FEATURE_NAME}
### Summary
- **Overall Status**: PASS / NEEDS REVISION
- **Critical Issues**: {count}
- **Warnings**: {count}
### Completeness (X/5 sections)
| Section | Status | Issue |
|---------|--------|-------|
| Problem | PASS/FAIL | {detail if fail} |
| Users | PASS/FAIL | {detail if fail} |
| Scope | PASS/FAIL | {detail if fail} |
| Success | PASS/FAIL | {detail if fail} |
| Risks | PASS/FAIL | {detail if fail} |
### Clarity Issues
- [ ] {Issue 1}
- [ ] {Issue 2}
### Consistency Issues
- [ ] {Contradiction 1}
### Open Questions (Require Stakeholder Input)
1. {Question needing clarification}
### Recommendations
1. {Specific fix recommendation}
Common Validation Failures
| Failure |
Detection |
Resolution |
| Vague success metric |
"Improve", "faster", "better" |
Quantify with numbers |
| Missing non-goals |
No explicit exclusions |
Ask "What are we NOT doing?" |
| Undefined edge cases |
Happy path only |
Apply "3 AM Test" |
| Policy contradiction |
Rule A conflicts with Rule B |
Document precedence |
| Stakeholder conflict |
User A vs User B needs |
Explicit prioritization |
Integration Points
After requirements-discovery
Discovery Interview Complete
-> Draft *_FEATURE.md
-> spec-validation (this skill)
-> Identify gaps
-> Follow-up questions
-> Final draft
Before implementation
*_FEATURE.md Finalized
-> spec-validation final check
-> Engineering review
-> Implementation begins
Quick Checklist (Copy/Paste)
### Pre-Finalization Checklist
- [ ] Problem is specific, not vague
- [ ] Success metrics are quantified
- [ ] Non-goals are explicitly stated
- [ ] No TBD/TODO items remain
- [ ] Acronyms defined
- [ ] Edge cases documented
- [ ] Error messages are user-actionable
- [ ] No policy contradictions
- [ ] Trade-offs explicitly documented
- [ ] Priorities clear (must-have vs nice-to-have)
- [ ] Technical constraints validated
- [ ] Dependencies identified
- [ ] Risks have mitigation plans
majiayu000