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

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

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

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

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.

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

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 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)

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

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

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

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