Pre-implementation story validation with 10-step comprehensive assessment including template compliance, anti-hallucination verification, and implementation readiness scoring. This skill should be used before handing story to development agent.
Pre-implementation story validation with 10-step comprehensive assessment including template compliance, anti-hallucination verification, and implementation readiness scoring. This skill should be used before handing story to development agent.
acceptance
[{"validation_complete":"All 10 validation steps executed successfully"},{"go_no_go_decision":"Clear GO or NO-GO decision with confidence level"},{"report_generated":"Validation report created with findings and recommendations"},{"critical_issues_identified":"All blocking issues identified and documented"}]
inputs
{"story_file":{"type":"string","required":true,"description":"Path to story file in .claude/stories/{epic-id}/{story-id}.md format"},"validation_mode":{"type":"enum","values":["full","quick","critical_only"],"default":"full","description":"Validation depth: full (all 10 steps), quick (critical steps only), critical_only (blocking issues)"}}
outputs
{"validation_passed":{"type":"boolean","description":"GO (true) or NO-GO (false) decision"},"readiness_score":{"type":"number","description":"Implementation readiness score (1-10)"},"confidence_level":{"type":"enum","values":["High","Medium","Low"],"description":"Confidence in successful implementation"},"critical_issues":{"type":"array","description":"Must-fix issues blocking implementation"},"should_fix_issues":{"type":"array","description":"Important quality improvements (recommended)"},"nice_to_have":{"type":"array","description":"Optional enhancements"},"anti_hallucination_findings":{"type":"array","description":"Unverifiable claims or invented details"}}
Pre-implementation story validation with comprehensive 10-step assessment to catch issues before development begins.
Purpose
Before handing a story to James (Developer Agent), validate that the story is complete, accurate, and implementable. Catch template gaps, hallucinated details, and missing context that would cause implementation failures.
Core Principles:
Comprehensive - 10 validation steps cover all critical aspects
Anti-hallucination - Verify all technical claims against source documents
Actionable - Every issue has clear fix guidance
GO/NO-GO clarity - Binary decision with confidence level
Educational - Report teaches story creators what to improve
Integration:
Input: Story markdown file from story creation process
See:references/validation-checklist.md for UI validation details
Step 4: Acceptance Criteria Satisfaction
Purpose: Ensure tasks will actually satisfy all acceptance criteria when implemented.
Actions:
Extract Acceptance Criteria:
From story "Acceptance Criteria" section:
List all ACs with IDs (AC1, AC2, AC3, ...)
Extract Tasks:
From story "Tasks/Subtasks" section:
List all tasks with descriptions
Map Tasks to ACs:
For each AC:
Find tasks that address this AC
Verify tasks are sufficient to satisfy AC
Identify Gaps:
Coverage Analysis:
AC1 "User can log in" → Task 1.1, Task 1.2 ✅
AC2 "Password reset works" → Task 2.1 ✅
AC3 "Session timeout" → No tasks found ❌
Gaps:
- AC3 has no implementing tasks
- AC4 partially covered (only happy path, no error cases)
Verify AC Testability:
For each AC:
✅ Measurable (can verify success/failure)
✅ Specific (not vague like "should work well")
✅ Has success criteria
Report AC Issues:
Critical Issues:
- AC3 "Session timeout" has no implementing tasks
- AC5 too vague: "System should be secure" (not measurable)
Should-Fix:
- AC2 missing error case testing
- AC4 missing edge case handling
Validation Criteria:
✅ All ACs have implementing tasks
✅ Tasks sufficient to satisfy ACs
✅ ACs are testable and measurable
✅ Edge cases covered
Outputs:
uncovered_acs[] - ACs with no implementing tasks
partial_coverage_acs[] - ACs partially covered
vague_acs[] - ACs not measurable/testable
See:references/validation-checklist.md for AC validation rules
Step 5: Validation and Testing Instructions
Purpose: Ensure testing approach is clear and comprehensive.
✅ Test data needs identified (fixtures, mocks, seeds)
✅ Test environment specified (local, staging, CI)
Report Testing Issues:
Critical Issues:
- No test scenarios for AC3
- Testing section says "test manually" (not specific)
Should-Fix:
- Missing integration test scenarios
- No test data requirements specified
Validation Criteria:
✅ Test approach clarity
✅ Test scenarios identified
✅ Validation steps clear
✅ Testing tools specified
✅ Test data requirements identified
Outputs:
missing_test_scenarios[] - ACs without test scenarios
Critical Issues:
- Story involves password storage but no hashing requirements specified
- No input validation mentioned for user registration
Should-Fix:
- Missing rate limiting requirements
- No mention of HTTPS enforcement
Validation Criteria (for security stories):
✅ Security requirements identified
✅ Authentication/authorization specified
✅ Data protection clear
✅ Vulnerability prevention addressed
✅ Compliance requirements addressed
Outputs:
security_gaps[] - Missing security requirements
compliance_issues[] - Compliance gaps
See:references/validation-checklist.md for security validation
Step 7: Tasks/Subtasks Sequence Validation
Purpose: Ensure tasks are in logical order with clear dependencies.
Actions:
Extract Task Sequence:
From "Tasks/Subtasks":
List tasks in order
Identify dependencies
Validate Logical Order:
✅ Prerequisites before dependent tasks (e.g., create model before controller)
✅ Setup tasks before implementation tasks
✅ Implementation before testing
✅ No circular dependencies
Check Task Granularity:
✅ Tasks are appropriately sized (not too broad, not too granular)
✅ Each task is actionable (clear what to do)
✅ Tasks are testable (can verify completion)
Verify Completeness:
✅ All necessary tasks present
✅ No missing steps between tasks
✅ All ACs covered by tasks (cross-check with Step 4)
task_dependency_issues[] - Circular or unclear dependencies
task_granularity_issues[] - Tasks too broad or too fine
See:references/validation-checklist.md for task validation
Step 8: Anti-Hallucination Verification
Purpose: Verify all technical claims are traceable to source documents, not invented.
Actions:
Extract Technical Claims:
From story (Dev Notes, Tasks, File List):
File/directory names
Library/framework names
API endpoints
Database tables/columns
Architecture patterns
Configuration settings
Verify Against Sources:
File/Directory Claims:
✅ Check against docs/unified-project-structure.md
❌ Flag files/dirs not in project structure
Library/Framework Claims:
✅ Check against package.json, requirements.txt, architecture docs
❌ Flag libraries not in dependencies
API Endpoint Claims:
✅ Check against docs/architecture/api-spec.md
❌ Flag endpoints not documented
Database Claims:
✅ Check against docs/architecture/database-schema.md
❌ Flag tables/columns not in schema
Architecture Pattern Claims:
✅ Check against docs/architecture/ docs
❌ Flag patterns not documented
Identify Hallucinations:
Anti-Hallucination Findings:
Critical:
- Story claims "bcrypt library" but not in package.json dependencies
- References "auth-service.ts" but no such file in project structure
- Mentions "Redis cache" but architecture docs don't specify Redis
Should-Fix:
- Claims "JWT authentication" but architecture uses sessions
- References "/api/users" endpoint not in API spec
Flag Unverifiable Claims:
Claims with no source reference
Details too specific to be general knowledge
Technical choices not documented in architecture
Validation Criteria:
✅ Source verification (all claims traceable)
✅ Architecture alignment (matches specs)
✅ No invented details (all backed by sources)
✅ Reference accuracy (sources correct and accessible)
Outputs:
hallucinated_files[] - Files/dirs not in project
hallucinated_libs[] - Libraries not in dependencies
hallucinated_apis[] - API endpoints not documented
hallucinated_patterns[] - Patterns not in architecture
See:references/validation-checklist.md for anti-hallucination checks
Step 9: Dev Agent Implementation Readiness
Purpose: Assess if story provides sufficient context for developer agent to implement without external docs.
Actions:
Check Self-Contained Context:
✅ All necessary technical details in story (not requiring external doc reading)
✅ Dev Notes section comprehensive
✅ File structure clear
✅ Implementation approach specified
Verify Clear Instructions:
✅ Tasks are unambiguous (developer knows exactly what to do)
✅ No vague instructions ("implement as needed", "use best practices")
✅ Technical choices specified (which library, which pattern)
Assess Complete Technical Context:
From Dev Notes:
✅ Technical approach explained
✅ Key implementation details provided
✅ Potential gotchas mentioned
✅ Integration points documented
Identify Missing Information:
Implementation Readiness Issues:
Critical:
- Dev Notes missing: No technical approach specified
- Vague task: "Implement authentication" (which method? OAuth? JWT? Sessions?)
Should-Fix:
- Missing integration details: How does this connect to existing auth system?
- No error handling guidance
Score Implementation Readiness:
Readiness Score (1-10):
9-10: Fully ready, developer can start immediately
7-8: Minor gaps, easily filled during implementation
5-6: Significant gaps, requires clarification before starting
3-4: Major gaps, story needs substantial rework
1-2: Not ready, critical information missing
Validation Criteria:
✅ Self-contained context (no external docs needed)
✅ Clear instructions (unambiguous steps)
✅ Complete technical context (all details in Dev Notes)
✅ All tasks actionable
Outputs:
readiness_score - Score 1-10
missing_context[] - Missing technical details
vague_instructions[] - Ambiguous tasks
external_refs_needed[] - References to external docs required
See:references/validation-checklist.md for readiness assessment
Step 10: Generate Validation Report
Purpose: Synthesize all validation findings into actionable report with GO/NO-GO decision.
Actions:
Categorize Issues:
Critical Issues (Must Fix - Story Blocked):
Missing required sections
Unfilled placeholders
Uncovered acceptance criteria
Hallucinated technical details
Circular task dependencies
Should-Fix Issues (Important Quality):
Vague testing instructions
Missing security considerations
Incomplete file structure
Poor task granularity
Nice-to-Have (Optional Enhancements):
Additional test scenarios
More detailed Dev Notes
Better task descriptions
Calculate Readiness Score:
Readiness Score Calculation:
Base: 10 points
Deductions:
- Critical issues: -2 points each
- Should-fix issues: -0.5 points each
- Anti-hallucination findings: -1 point each
Score = max(1, 10 - total_deductions)
Determine Confidence Level:
High: Readiness ≥ 8, no critical issues, ≤2 should-fix
