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:

1. •

   Load Story File:

   Use Claude Code Read tool:

   code

   Read: .claude/stories/{epic-id}/{story-id}.md
   

   Extract metadata:

   • •Story ID
   • •Epic ID (if referenced)
   • •Title
   • •Status
   • •All sections
2. •

   Load Story Template:

   code

   Read: .claude/skills/planning/create-story/references/templates.md
   

   Extract template structure:

   • •Required sections
   • •Optional sections
   • •Expected placeholders
3. •

   Load Parent Epic (if applicable):

   If story references epic:

   code

   Read: .claude/epics/{epic-id}.md
   

   Verify story aligns with epic objectives.

4. •

   Load Project Structure:

   code

   Read: docs/unified-project-structure.md
   

   For validating file paths and directory structure.

5. •

   Load Architecture Docs (for anti-hallucination):

   code

   Read: docs/architecture/*.md
   

   For verifying technical claims.

Outputs:

• •story_content - Full story text
• •template_sections[] - Required sections from template
• •epic_context - Parent epic details
• •project_structure - Expected file/directory layout
• •architecture_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:

1. •

   Extract Story Sections:

   Parse story markdown to extract sections:

   • •Objective
   • •Context
   • •Acceptance Criteria
   • •Tasks/Subtasks
   • •Dev Notes
   • •Testing & Validation
   • •File List
   • •Dependencies
   • •etc.
2. •

   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)
3. •

   Check for Unfilled Placeholders:

   Search for placeholder patterns:

   • •{{EpicNum}}, {{StoryNum}}, {{var}}
   • •_TBD_, [TBD], TODO
   • •..., [more details needed]
4. •

   Report Missing/Incomplete Sections:

   code

   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 found
• •unfilled_placeholders[] - Placeholder patterns still in story
• •empty_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:

1. •

   Extract File References:

   From story sections (File List, Tasks, Dev Notes):

   • •New files to create
   • •Existing files to modify
   • •Directories mentioned
2. •

   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)
3. •

   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
4. •

   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
5. •

   Report File Structure Issues:

   code

   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 structure
• •inconsistent_dirs[] - Directory naming issues
• •file_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:

1. •

   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
2. •

   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
3. •

   Report UI Completeness Issues:

   code

   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 gaps
• •ui_design_issues[] - Design/styling gaps
• •ui_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:

1. •

   Extract Acceptance Criteria:

   From story "Acceptance Criteria" section:

   • •List all ACs with IDs (AC1, AC2, AC3, ...)
2. •

   Extract Tasks:

   From story "Tasks/Subtasks" section:

   • •List all tasks with descriptions
3. •

   Map Tasks to ACs:

   For each AC:

   • •Find tasks that address this AC
   • •Verify tasks are sufficient to satisfy AC
4. •

   Identify Gaps:

   code

   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)
   

5. •

   Verify AC Testability:

   For each AC:

   • •✅ Measurable (can verify success/failure)
   • •✅ Specific (not vague like "should work well")
   • •✅ Has success criteria
6. •

   Report AC Issues:

   code

   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.

Actions:

1. •

   Extract Testing Section:

   From "Testing & Validation" section:

   • •Test approach
   • •Test scenarios
   • •Validation steps
   • •Testing tools
2. •

   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.)
3. •

   Check Test Coverage:

   For each AC:

   • •✅ Has corresponding test scenarios
   • •✅ Happy path tested
   • •✅ Error cases tested
   • •✅ Edge cases tested
4. •

   Verify Test Data Requirements:

   • •✅ Test data needs identified (fixtures, mocks, seeds)
   • •✅ Test environment specified (local, staging, CI)
5. •

   Report Testing Issues:

   code

   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
• •vague_testing[] - Non-specific testing instructions
• •test_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:

1. •

   Detect Security-Critical Story:

   Keywords: "auth", "password", "token", "encryption", "secure", "permission", "access control"

2. •

   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
3. •

   Report Security Issues:

   code

   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:

1. •

   Extract Task Sequence:

   From "Tasks/Subtasks":

   • •List tasks in order
   • •Identify dependencies
2. •

   Validate Logical Order:

   • •✅ Prerequisites before dependent tasks (e.g., create model before controller)
   • •✅ Setup tasks before implementation tasks
   • •✅ Implementation before testing
   • •✅ No circular dependencies
3. •

   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)
4. •

   Verify Completeness:

   • •✅ All necessary tasks present
   • •✅ No missing steps between tasks
   • •✅ All ACs covered by tasks (cross-check with Step 4)
5. •

   Report Task Sequence Issues:

   code

   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 order
• •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:

1. •

   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
2. •

   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
3. •

   Identify Hallucinations:

   code

   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
   

4. •

   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:

1. •

   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
2. •

   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)
3. •

   Assess Complete Technical Context:

   From Dev Notes:

   • •✅ Technical approach explained
   • •✅ Key implementation details provided
   • •✅ Potential gotchas mentioned
   • •✅ Integration points documented
4. •

   Identify Missing Information:

   code

   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
   

5. •

   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:

1. •

   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
2. •

   Calculate Readiness Score:

   code

   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)
   

3. •

   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
4. •

   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
5. •

   Generate Report:

   markdown

   # 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 Structure: ✅ PASS / ⚠️ CONCERNS / ❌ FAIL
   - File paths match project structure
   - Consistent directory naming
   
   [... continue for all 10 validation steps ...]
   
   ## Critical Issues (Must Fix): {count}
   
   1. [SECTION] Description
      - Location: {section name or line number}
      - Fix: {how to fix}
   
   ## Should-Fix Issues (Recommended): {count}
   
   1. [SECTION] Description
      - Recommendation: {how to improve}
   
   ## Anti-Hallucination Findings: {count}
   
   1. Claim "{detail}" not verified in {source}
      - Fix: Remove or source from architecture docs
   
   ## Recommendation
   
   {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.
   
   ## Next Steps
   
   {If GO}:
   - Hand to James: @james *implement {story-id}
   - Monitor for should-fix issues during implementation
   
   {If NO-GO}:
   1. Fix critical issues listed above
   2. Re-validate: @validate-story {story-file}
   3. Proceed once validation passes
   

Outputs:

• •validation_report - Full markdown report
• •validation_passed - Boolean GO/NO-GO
• •readiness_score - Number 1-10
• •confidence_level - High/Medium/Low
• •critical_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:

# Step 1: Create story
@create-story epic-001 story-003 "User Authentication"

# Step 2: Validate story
@validate-story .claude/stories/epic-001/story-003.md

# If GO:
@james *implement story-003

# If NO-GO:
# Fix critical issues, re-validate
@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

1. •Always validate before implementation - Catch issues early
2. •Fix critical issues first - Don't proceed with NO-GO stories
3. •Address should-fix during implementation - Don't block on minor issues
4. •Re-validate after fixes - Ensure issues resolved
5. •Track anti-hallucination patterns - Learn common mistakes
6. •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 schema
• •references/validation-checklist.md - Detailed checklist for all 10 steps
• •references/examples.md - GO and NO-GO validation examples

Part of BMAD Enhanced Planning Suite - Ensures quality stories before implementation