/story-validate

Validate a story's completeness, clarity, and readiness for development before assigning to an agent.

Quick Start

Copy/agileflow:story-validate STORY=<US-ID>

Parameters

Examples

Validate Before Development

Copy/agileflow:story-validate STORY=US-0042

Performs comprehensive validation on the story and returns a detailed report showing what's complete and what needs fixing.

Check a Story from Different Epic

Copy/agileflow:story-validate STORY=US-0085

The command automatically locates the story file regardless of which epic it belongs to.

Output

The validation report includes:

PASSED Checks

Shows all validation criteria that passed:

• Required sections present
• Acceptance criteria clear and testable
• Architecture context populated with sources
• Dependencies documented
• Estimation is realistic

FAILED Issues

Shows critical problems that must be fixed:

• Missing required sections (AC, Architecture Context)
• Unclear acceptance criteria (not Given/When/Then format)
• Missing source citations in architecture context
• Unverified dependencies
• Unrealistic estimation

WARNINGS

Shows minor issues or suggestions:

• Dependencies could be clearer
• Acceptance criteria could be more specific
• Dev Agent Record placeholder text
• Suggested improvements

Validation Checklist

The command validates:

1. Required Sections

• Story metadata (ID, epic, owner, estimate, status)
• Description
• Acceptance Criteria (Given/When/Then format)
• Architecture Context with subsections
• Testing Strategy
• Dev Agent Record (structure)
• Dependencies (if applicable)

2. Acceptance Criteria Quality

• Uses Given/When/Then format (not bullet points alone)
• 2-5 criteria (not too many, not too few)
• Specific and measurable
• References implementation details
• Each criterion is independently testable

3. Architecture Context

• Section exists with real content
• Includes source citations: [Source: architecture/{file}.md#{section}]
• All referenced files exist in docs/04-architecture/
• Content is extracted (not invented)

4. Estimation

• Estimate is one of: 0.5d, 1d, 1.5d, 2d
• For >2d: suggests breaking into smaller stories
• Realistic for story scope

5. Dependencies

• Format is clear: "Depends on US-#### (description)"
• Referenced stories exist in status.json
• No circular dependencies
• Blocked stories have documented reasons

Workflow

1. Create story - Use /story to create new story
2. Validate completeness - Run /story-validate to check before development
3. Fix issues - Address any failed checks or warnings
4. Run again - Re-validate after fixes
5. Develop - Story is ready when all checks pass

Example Report

Copy🔍 Story Validation Report
==========================
Story: US-0042 - User login form
File: docs/06-stories/EP-0010/US-0042-user-login-form.md
Status: ready
 
✅ PASSED (11 checks)
------------------
- All required sections present
- Acceptance criteria in proper format
- Architecture context populated
- All source citations valid
- Dependencies documented
- Estimate is realistic
- Owner assigned and appropriate
- Dev Agent Record structured
- No circular dependencies detected
- Story within epic scope
- Title is clear and descriptive
 
❌ FAILED (0 issues)
-------------------
[None]
 
⚠️ WARNINGS (1 issue)
-----------------------
Warning: Architecture Context could be more detailed
  Suggestion: Add more specific API endpoint references
 
📊 SUMMARY
----------
Architecture Context: ✓ populated
Acceptance Criteria: ✓ clear
Dependencies: ✓ documented
Dev Agent Record: ✓ structured
Ready for Development: YES
 
Next Steps:
1. Story is ready! Assign to owner with /agileflow:assign US-0042
2. Or include in next sprint with /agileflow:sprint

Common Issues and Fixes

Issue: "Architecture Context missing"

Fix: Add sections for Data Models, API Specs, Components with source citations to docs/04-architecture/.

Issue: "Acceptance criteria not in Given/When/Then format"

Fix: Rewrite criteria following the pattern:

Copy- Given [precondition]
  When [action]
  Then [expected outcome]

Issue: "Source citation not found"

Fix: Verify the file exists in docs/04-architecture/ and use correct section anchor.

Issue: "Estimate seems high for scope"

Fix: Consider breaking story into smaller ones or providing justification in Technical Notes.

Issue: "Circular dependency detected"

Fix: Review dependency chain and resolve - stories cannot be completed if they depend on each other.

Integration with Other Commands

• After creation: Always run /story-validate before assigning
• Before assignment: Use /assign only after validation passes
• Before sprint: Use /sprint with validated stories
• During development: Reference validation report for context
• For updates: Re-validate if story is significantly modified

Best Practices

• Validate before assigning - Catch issues early before development starts
• Review failed checks carefully - Each one has a specific suggestion
• Don't ignore warnings - They often indicate quality improvements
• Use architecture docs - Proper citations make stories clearer for developers
• Keep AC focused - 2-5 criteria that cover main scenarios
• Test your stories - Validation checks clarity, not correctness

Related Commands

• /story - Create new stories
• /epic - Create parent epic
• /assign - Assign validated stories to owners
• /sprint - Include validated stories in sprint
• /babysit - Get help during development
• /deps - Visualize story dependencies