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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
