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