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: `` Read: .claude/stories/{epic-id}/{story-id}.md ``

Extract metadata: - Story ID - Epic ID (if referenced) - Title - Status - All sections

1. Load Story Template:

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

Extract template structure: - Required sections - Optional sections - Expected placeholders

1. Load Parent Epic (if applicable):

If story references epic: `` Read: .claude/epics/{epic-id}.md ``

Verify story aligns with epic objectives.

1. Load Project Structure:

`` Read: docs/unified-project-structure.md ``

For validating file paths and directory structure.

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

1. Extract Story Sections:

Parse story markdown to extract sections: - Objective - Context - Acceptance Criteria - Tasks/Subtasks - Dev Notes - Testing & Validation - File List - Dependencies - etc.

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

1. Check for Unfilled Placeholders:

Search for placeholder patterns: - {{EpicNum}}, {{StoryNum}}, {{var}} - TBD, [TBD], TODO - ..., [more details needed]

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

1. Extract File References:

From story sections (File List, Tasks, Dev Notes): - New files to create - Existing files to modify - Directories mentioned

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

1. 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

1. 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

1. 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
• filelocationissues[] - 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

1. 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

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

• uicomponentissues[] - Component specification gaps
• uidesignissues[] - Design/styling gaps
• uiinteractionissues[] - 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, ...)

1. Extract Tasks:

From story "Tasks/Subtasks" section: - List all tasks with descriptions

1. Map Tasks to ACs:

For each AC: - Find tasks that address this AC - Verify tasks are sufficient to satisfy AC

1. 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) ```

1. Verify AC Testability:

For each AC: - ✅ Measurable (can verify success/failure) - ✅ Specific (not vague like "should work well") - ✅ Has success criteria

1. 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
• partialcoverageacs[] - 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

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

1. Check Test Coverage:

For each AC: - ✅ Has corresponding test scenarios - ✅ Happy path tested - ✅ Error cases tested - ✅ Edge cases tested

1. Verify Test Data Requirements:

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

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

• missingtestscenarios[] - ACs without test scenarios
• vague_testing[] - Non-specific testing instructions
• testdatagaps[] - 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"

1. 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

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

1. Extract Task Sequence:

From "Tasks/Subtasks": - List tasks in order - Identify dependencies

1. Validate Logical Order:

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

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

1. Verify Completeness:

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

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

• taskorderissues[] - Tasks in wrong order
• taskdependencyissues[] - Circular or unclear dependencies
• taskgranularityissues[] - 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

1. 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

1. 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 ```

1. 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

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

1. Assess Complete Technical Context:

From Dev Notes: - ✅ Technical approach explained - ✅ Key implementation details provided - ✅ Potential gotchas mentioned - ✅ Integration points documented

1. 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 ```

1. 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
• externalrefsneeded[] - 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

1. 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) ```

1. 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

1. 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

1. 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
• criticalissues[], shouldfixissues[], niceto_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