Validate Story
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
- Processing: 10-step validation → Issue identification → Report generation
- Output: Validation report with GO/NO-GO decision + issues + recommendations
When to Use This Skill
This skill should be used when:
- Story just created, before implementation
- Story updated, needs re-validation
- Pre-sprint planning (validate backlog stories)
- Story handed from PO → Dev team
This skill should NOT be used when:
- Story already in implementation
- Quick review needed (use quick mode)
- Story is template/draft only
Prerequisites
- Story file exists in
.claude/stories/{epic-id}/{story-id}.md
- Story template available (for comparison)
- Parent epic file exists (if story references epic)
- Architecture/project docs available (for anti-hallucination checks)
10-Step Validation Workflow
Step 0: Load Configuration and Story
Purpose: Load project configuration, story file, template, and related documents.
Actions:
-
Load Story File:
Use Claude Code Read tool:
Read: .claude/stories/{epic-id}/{story-id}.md
Extract metadata:
- Story ID
- Epic ID (if referenced)
- Title
- Status
- All sections
-
Load Story Template:
Read: .claude/skills/planning/create-story/references/templates.md
Extract template structure:
- Required sections
- Optional sections
- Expected placeholders
-
Load Parent Epic (if applicable):
If story references epic:
Read: .claude/epics/{epic-id}.md
Verify story aligns with epic objectives.
-
Load Project Structure:
Read: docs/unified-project-structure.md
For validating file paths and directory structure.
-
Load Architecture Docs (for anti-hallucination):
Read: docs/architecture/*.md
For verifying technical claims.
Outputs:
story_content - Full story texttemplate_sections[] - Required sections from templateepic_context - Parent epic detailsproject_structure - Expected file/directory layoutarchitecture_docs[] - Technical reference docs
See: references/templates.md for story template structure
Step 1: Template Completeness Validation
Purpose: Ensure all required template sections present and no unfilled placeholders.
Actions:
-
Extract Story Sections:
Parse story markdown to extract sections:
- Objective
- Context
- Acceptance Criteria
- Tasks/Subtasks
- Dev Notes
- Testing & Validation
- File List
- Dependencies
- etc.
-
Compare with Template:
For each required section in template:
- ✅ Section exists in story
- ✅ Section has content (not empty)
- ✅ Section content is meaningful (not placeholder text)
-
Check for Unfilled Placeholders:
Search for placeholder patterns:
{{EpicNum}}, {{StoryNum}}, {{var}}_TBD_, [TBD], TODO..., [more details needed]
-
Report Missing/Incomplete Sections:
Critical Issues:
- Missing section: "Testing & Validation"
- Unfilled placeholder: {{EpicNum}} in Objective
- Empty section: "Dependencies"
Should-Fix:
- Section "Dev Notes" has only 2 lines (expected detailed technical context)
Validation Criteria:
- ✅ All required sections present
- ✅ No unfilled placeholders (
{{var}}, _TBD_)
- ✅ Sections have meaningful content (>3 lines for substantial sections)
Outputs:
missing_sections[] - Required sections not foundunfilled_placeholders[] - Placeholder patterns still in storyempty_sections[] - Sections with no/minimal content
See: references/validation-checklist.md for detailed template requirements
Step 2: File Structure and Source Tree Validation
Purpose: Verify file paths, directory structure, and source tree references are accurate and consistent.
Actions:
-
Extract File References:
From story sections (File List, Tasks, Dev Notes):
- New files to create
- Existing files to modify
- Directories mentioned
-
Validate File Paths:
For each file path:
- ✅ Matches project structure (src/, tests/, docs/)
- ✅ Uses consistent separators (forward slashes)
- ✅ No absolute paths (only relative to project root)
- ✅ File extensions correct (.ts, .js, .md, .yaml)
-
Check Directory Consistency:
- ✅ All files in same directory use consistent structure
- ✅ Test files in test directory
- ✅ Source files in source directory
- ✅ No mixing of unrelated files
-
Verify Source Tree References:
If story mentions project structure:
- ✅ References valid directories from
docs/unified-project-structure.md
- ✅ Directory names match exactly (case-sensitive)
- ✅ No invented directories not in project
-
Report File Structure Issues:
Critical Issues:
- File path uses Windows separators: "src\auth\login.ts" (should be "src/auth/login.ts")
- Referenced directory doesn't exist: "src/services/auth/" (project has "src/auth/")
Should-Fix:
- Test file in source directory: "src/api/user.test.ts" (should be "tests/api/user.test.ts")
Validation Criteria:
- ✅ File paths match project structure
- ✅ Consistent directory naming
- ✅ Appropriate file locations (tests in tests/, src in src/)
- ✅ No invented directories
Outputs:
invalid_paths[] - File paths that don't match project structureinconsistent_dirs[] - Directory naming issuesfile_location_issues[] - Files in wrong locations
See: references/validation-checklist.md for file structure rules
Step 3: UI/Frontend Completeness (if applicable)
Purpose: For frontend/UI stories, ensure design, components, and interactions are fully specified.
Actions:
-
Detect UI Story:
Check if story involves frontend:
- Keywords: "UI", "component", "page", "view", "styling", "responsive"
- File references:
.tsx, .vue, .jsx, .html, .css
- Tasks mention UI/UX work
-
If UI Story, Validate:
Component Specifications:
- ✅ Component names specified
- ✅ Component hierarchy clear (parent/child)
- ✅ Props/inputs documented
Styling/Design:
- ✅ Design guidance provided (colors, spacing, layout)
- ✅ Responsive behavior specified (mobile, tablet, desktop)
- ✅ Accessibility requirements mentioned (ARIA, keyboard nav)
User Interactions:
- ✅ User flows documented (click → modal → submit)
- ✅ Form validation specified
- ✅ Error states defined
Frontend-Backend Integration:
- ✅ API endpoints specified
- ✅ Data models documented
- ✅ Loading states defined
-
Report UI Completeness Issues:
Critical Issues:
- No responsive design guidance (mobile/tablet behavior undefined)
Should-Fix:
- Missing accessibility requirements (ARIA labels, keyboard navigation)
- Form validation rules not specified
Validation Criteria (for UI stories):
- ✅ Component specifications sufficient
- ✅ Styling/design guidance clear
- ✅ User interaction flows specified
- ✅ Responsive/accessibility addressed
- ✅ Frontend-backend integration clear
Outputs:
ui_component_issues[] - Component specification gapsui_design_issues[] - Design/styling gapsui_interaction_issues[] - User flow gaps
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 taskspartial_coverage_acs[] - ACs partially coveredvague_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.
Actions:
-
Extract Testing Section:
From "Testing & Validation" section:
- Test approach
- Test scenarios
- Validation steps
- Testing tools
-
Validate Test Approach:
- ✅ Testing strategy clear (unit, integration, e2e)
- ✅ Test scenarios identified
- ✅ Validation steps specific (not just "test it")
- ✅ Testing tools specified (Jest, Pytest, Mocha, etc.)
-
Check Test Coverage:
For each AC:
- ✅ Has corresponding test scenarios
- ✅ Happy path tested
- ✅ Error cases tested
- ✅ Edge cases tested
-
Verify Test Data Requirements:
- ✅ 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 scenariosvague_testing[] - Non-specific testing instructionstest_data_gaps[] - Missing test data requirements
See: references/validation-checklist.md for testing validation
Step 6: Security Considerations (if applicable)
Purpose: For security-critical stories, ensure security requirements are identified and addressed.
Actions:
-
Detect Security-Critical Story:
Keywords: "auth", "password", "token", "encryption", "secure", "permission", "access control"
-
If Security-Critical, Validate:
Security Requirements:
- ✅ Authentication/authorization specified
- ✅ Data protection requirements clear (encryption, hashing)
- ✅ Input validation requirements specified
- ✅ Vulnerability prevention addressed (SQL injection, XSS, CSRF)
Compliance:
- ✅ Regulatory requirements mentioned (GDPR, PCI-DSS, HIPAA)
- ✅ Security best practices referenced
-
Report Security Issues:
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 requirementscompliance_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)
-
Report Task Sequence Issues:
Critical Issues:
- Task 3 depends on Task 5 (circular dependency)
- Task 2 "Implement controller" before Task 1 "Create model" (wrong order)
Should-Fix:
- Task granularity too broad: "Implement entire auth system" (break down)
- Missing task: "Add integration tests" (not in task list)
Validation Criteria:
- ✅ Logical order (dependencies before dependents)
- ✅ Appropriate granularity
- ✅ Complete (all steps present)
- ✅ Actionable (clear instructions)
Outputs:
task_order_issues[] - Tasks in wrong ordertask_dependency_issues[] - Circular or unclear dependenciestask_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 projecthallucinated_libs[] - Libraries not in dependencieshallucinated_apis[] - API endpoints not documentedhallucinated_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-10missing_context[] - Missing technical detailsvague_instructions[] - Ambiguous tasksexternal_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
- Medium: Readiness 5-7, ≤3 critical issues, ≤5 should-fix
- Low: Readiness ≤4, >3 critical issues, or >5 should-fix
-
Make GO/NO-GO Decision:
GO Criteria:
- No critical issues, OR
- ≤2 critical issues AND readiness ≥ 7
NO-GO Criteria:
-
2 critical issues, OR
- Readiness < 7, OR
- Any critical anti-hallucination findings
-
Generate Report:
# Story Validation Report
**Story:** {epic-id}/{story-id} - {title}
**Validated:** {date}
**Validator:** validate-story skill
## Summary
**Decision:** GO / NO-GO
**Readiness Score:** {score}/10
**Confidence Level:** High / Medium / Low
## Validation Results
### Template Compliance: ✅ PASS / ❌ FAIL
All required sections present
No unfilled placeholders
File paths match project structure
Consistent directory naming
[... continue for all 10 validation steps ...]
[SECTION] Description
Location: {section name or line number}
Fix: {how to fix}
[SECTION] Description
Recommendation: {how to improve}
Claim "{detail}" not verified in {source}
Fix: Remove or source from architecture docs
{GO/NO-GO} - {rationale}
{If NO-GO}: Fix {count} critical issues before handing to James.
{If GO}: Proceed to implementation. Address {count} should-fix issues during development.
{If GO}:
Hand to James: @james
Outputs:
validation_report - Full markdown reportvalidation_passed - Boolean GO/NO-GOreadiness_score - Number 1-10confidence_level - High/Medium/Lowcritical_issues[], should_fix_issues[], nice_to_have[]
See: references/templates.md for full report template
Execution Complete
Skill complete when:
- ✅ All 10 validation steps executed
- ✅ Issues categorized (critical/should-fix/nice-to-have)
- ✅ Readiness score calculated
- ✅ GO/NO-GO decision made
- ✅ Validation report generated
- ✅ Telemetry emitted
Integration with Workflow
Story Creation → Validation → Implementation Flow:
@create-story epic-001 story-003 "User Authentication"
@validate-story .claude/stories/epic-001/story-003.md
@james *implement story-003
@validate-story .claude/stories/epic-001/story-003.md
Who Invokes:
- Product Owner (before accepting story)
- Scrum Master (during sprint planning)
- Story creator (self-validation)
- James (auto-validate before implementation - optional)
Best Practices
- Always validate before implementation - Catch issues early
- Fix critical issues first - Don't proceed with NO-GO stories
- Address should-fix during implementation - Don't block on minor issues
- Re-validate after fixes - Ensure issues resolved
- Track anti-hallucination patterns - Learn common mistakes
- Use quick mode for drafts - Full mode for final validation
When to Escalate
Escalate to user when:
- Multiple anti-hallucination findings (>5)
- Architecture mismatch (story conflicts with architecture)
- Unclear requirements (story too vague to validate)
- Missing epic context (epic file not found)
- Template version mismatch (story uses old template)
References
references/templates.md - Validation report format, story template schemareferences/validation-checklist.md - Detailed checklist for all 10 stepsreferences/examples.md - GO and NO-GO validation examples
Part of BMAD Enhanced Planning Suite - Ensures quality stories before implementation
