/sdd:story-validate

Meta

• Version: 2.0
• Category: quality-gates
• Complexity: medium
• Purpose: Final validation of story against acceptance criteria before production deployment

Definition

Purpose: Execute comprehensive final validation to ensure all acceptance criteria are met, all tests pass, and story is production-ready.

Syntax: /sdd:story-validate [story_id]

Parameters

Parameter	Type	Required	Default	Description	Validation
story_id	string	No	current branch	Story ID (STORY-YYYY-NNN)	Must match format STORY-YYYY-NNN

INSTRUCTION: Execute Final Story Validation

INPUTS

• story_id: Story identifier (auto-detected from branch if not provided)
• Project context from /docs/project-context/ directory
• Story file from /docs/stories/qa/[story-id].md
• Complete test suite results from QA
• Acceptance criteria from story file

PROCESS

Phase 1: Project Context Loading

1. CHECK if /docs/project-context/ directory exists
2. IF missing:
   • SUGGEST running /sdd:project-init first
   • EXIT with initialization guidance
3. LOAD project-specific validation requirements from:
   • /docs/project-context/technical-stack.md - Testing tools and validation methods
   • /docs/project-context/coding-standards.md - Quality thresholds and criteria
   • /docs/project-context/development-process.md - Validation stage requirements

Phase 2: Story Identification & Validation

1. IF story_id NOT provided:

   • DETECT current git branch
   • EXTRACT story ID from branch name
   • EXAMPLE: Branch feature/STORY-2025-001-auth → ID STORY-2025-001

2. VALIDATE story exists and is ready:

   • CHECK /docs/stories/qa/[story-id].md exists
   • IF NOT found in QA:
     • CHECK if in /docs/stories/development/ or /docs/stories/review/
     • ERROR: "Story must complete QA before validation"
     • SUGGEST appropriate command to progress
   • IF in /docs/stories/completed/:
     • ERROR: "Story already completed and shipped"
   • IF NOT found anywhere:
     • ERROR: "Story [story-id] not found"
     • EXIT with guidance

3. READ story file for:

   • Success Criteria (acceptance criteria)
   • Implementation Checklist
   • QA Checklist
   • Technical Notes and concerns
   • Rollback Plan

Phase 3: Acceptance Criteria Validation

3.1 Load and Parse Criteria

1. EXTRACT all acceptance criteria from Success Criteria section
2. COUNT total criteria
3. IDENTIFY browser test mappings from QA results

3.2 Validate Each Criterion

1. FOR each acceptance criterion:

   ✓ [Criterion]: PASSED/FAILED
     How tested: [Discovered browser testing framework]
     Evidence: [Test file path and line number]
     Screenshots: [Screenshot path]
     Validation method: [Automated browser test/Manual verification]
   

2. MAP criteria to browser tests:

   • Laravel: tests/Browser/[StoryId]Test.php
   • Node.js Playwright: tests/e2e/[story-id].spec.js
   • Python Playwright: tests/browser/test_[story_id].py

3. VERIFY test evidence:

   • READ test file to confirm test exists
   • CHECK QA results for test pass status
   • VALIDATE screenshot exists (if applicable)
   • CONFIRM test actually validates the criterion

4. MARK criterion validation:

   ## Success Criteria
   - [x] User can toggle dark mode
     * Tested by: tests/Browser/DarkModeTest.php::line 45
     * Evidence: Browser test passed, screenshot saved
     * Validated: 2025-10-01
   

Phase 4: Implementation Completeness Check

4.1 Core Features Validation

1. CHECK Implementation Checklist:

   ✅ Core Features (using discovered standards):
   - [x] Feature implementation → Code complete and functional
   - [x] Unit tests → 87% coverage (target: 80% from standards)
   - [x] Integration tests → All feature tests passing
   - [x] Browser test coverage → 100% of acceptance criteria
   - [x] All discovered tests passing → Unit + Feature + Browser
   

2. VALIDATE each checklist item:

   • Feature implementation: CODE exists and works
   • Unit tests: COVERAGE meets threshold from coding-standards.md
   • Integration tests: ALL feature tests PASS
   • Browser tests: 100% acceptance criteria coverage
   • All tests passing: NO failures in any test suite

4.2 Quality Standards Validation

1. CHECK quality items:

   ✅ Quality Standards:
   - [x] Error handling → Try/catch blocks, graceful failures
   - [x] Loading states → Spinners, skeleton screens implemented
   - [x] Documentation → Code comments, README updated
   

2. VALIDATE:

   • Error handling: CHECK for try/catch, error boundaries, validation
   • Loading states: VERIFY wire:loading, spinners, feedback
   • Documentation: CONFIRM inline docs, updated README/CHANGELOG

4.3 Non-Functional Requirements

1. CHECK non-functional items:

   ✅ Non-Functional:
   - [x] Performance → Response times meet targets
   - [x] Accessibility → WCAG AA compliance
   - [x] Security → No vulnerabilities, auth working
   

2. VALIDATE from QA results:

   • Performance: METRICS from QA meet story targets
   • Accessibility: ARIA labels, keyboard nav, contrast checked
   • Security: NO vulnerabilities in audit, auth/authz verified

Phase 5: Rollback Plan Verification

1. CHECK if Rollback Plan section is populated

2. IF empty or minimal:

   • WARN: "Rollback plan should be documented"
   • SUGGEST rollback steps based on changes
   • OFFER to populate from git diff

3. VALIDATE rollback plan contains:

   • Clear steps to revert changes
   • Database migration rollback (if applicable)
   • Cache clearing instructions
   • Service restart procedures (if needed)
   • Verification steps after rollback

4. TEST rollback feasibility (if possible):

   • Verify migrations are reversible
   • Check for data loss risks
   • Confirm no breaking changes to shared code

Phase 6: Final Checks

6.1 Production Readiness Checklist

1. EXECUTE final readiness validation:

   🚀 READY FOR PRODUCTION?
   ════════════════════════════════════════════════
   
   ☑ All acceptance criteria met
   ☑ All tests passing
   ☑ All acceptance criteria covered by automated browser tests
   ☑ Browser test suite passes completely
   ☑ Code reviewed and approved
   ☑ Documentation complete
   ☑ Performance acceptable
   ☑ Security verified
   ☑ Rollback plan ready
   ☑ Monitoring configured (if applicable)
   
   CONFIDENCE LEVEL: [High/Medium/Low]
   

2. CALCULATE confidence level:

   • HIGH: All items ✓, no warnings, comprehensive tests
   • MEDIUM: All items ✓, some warnings, adequate tests
   • LOW: Missing items, concerns, or gaps in testing

6.2 Risk Assessment

1. IDENTIFY remaining risks:

   RISKS:
   - [Risk 1]: [Description] - Mitigation: [How to handle]
   - [Risk 2]: [Description] - Mitigation: [How to handle]
   

2. ASSESS risk levels:

   • Database migrations: Risk of data loss?
   • API changes: Breaking changes for consumers?
   • Dependency updates: Compatibility issues?
   • Performance impact: Degradation possible?
   • Security changes: New attack vectors?

6.3 Dependency Validation

1. CHECK external dependencies:

   DEPENDENCIES:
   - [Dependency 1]: [Status - Ready/Not Ready]
   - [Dependency 2]: [Status - Ready/Not Ready]
   

2. VALIDATE:

   • External services: Available and tested?
   • Third-party APIs: Credentials configured?
   • Database migrations: Run on staging?
   • Feature flags: Configured correctly?
   • Environment variables: Set in production?

Phase 7: Validation Report Generation

1. COMPILE all validation results

2. DETERMINE overall status:

   • ✅ READY TO SHIP: All checks pass, high confidence
   • ⚠️ NEEDS WORK: Critical items missing or failing

3. GENERATE validation report:

📄 VALIDATION SUMMARY
════════════════════════════════════════════════
Story: [STORY-ID] - [Title]
Validated: [Timestamp]
Validator: Claude Code (Automated)

RESULT: ✅ READY TO SHIP / ⚠️ NEEDS WORK

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 ACCEPTANCE CRITERIA: 5/5 PASSED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ User can toggle dark mode
  → tests/Browser/DarkModeTest.php::line 45 ✅
✓ Theme persists across sessions
  → tests/Browser/DarkModeTest.php::line 67 ✅
✓ All UI components support both themes
  → tests/Browser/DarkModeTest.php::line 89 ✅
✓ Keyboard shortcut (Cmd+Shift+D) works
  → tests/Browser/DarkModeTest.php::line 112 ✅
✓ Preference syncs across browser tabs
  → tests/Browser/DarkModeTest.php::line 134 ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 QUALITY METRICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Passed Criteria:     5/5 (100%)
Test Coverage:       87% (target: 80% ✅)
Quality Score:       9.2/10
Performance:         All targets met ✅
Security:            No vulnerabilities ✅
Accessibility:       WCAG AA compliant ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 PRODUCTION READINESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ All acceptance criteria met
✅ All tests passing (76/76)
✅ Browser test coverage: 100%
✅ Code reviewed and approved
✅ Documentation complete
✅ Performance acceptable
✅ Security verified
✅ Rollback plan documented

CONFIDENCE LEVEL: ✅ HIGH

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ RISKS & MITIGATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Low Risk: CSS changes may affect custom themes
  Mitigation: Browser tests cover theme switching,
              rollback plan ready

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔗 DEPENDENCIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ No external dependencies

[IF NOT READY:]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ BLOCKING ISSUES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Acceptance criterion "X" not validated by browser test
   → Create browser test in tests/Browser/
2. Rollback plan not documented
   → Add rollback steps to story file
3. Performance target not met (450ms vs 200ms)
   → Optimize database queries

[IF READY:]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ SHIP CHECKLIST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. /sdd:story-ship [story-id]             # Deploy to production
2. Monitor application after deployment
3. Be ready to execute rollback plan if needed
4. Document lessons learned after ship

Phase 8: Story File Updates

1. UPDATE Success Criteria with validation evidence:

   ## Success Criteria
   - [x] User can toggle dark mode
     * Tested by: tests/Browser/DarkModeTest.php::line 45
     * Evidence: Browser test passed on 2025-10-01
     * Screenshot: /storage/screenshots/STORY-2025-003/toggle.png
   - [x] Theme persists across sessions
     * Tested by: tests/Browser/DarkModeTest.php::line 67
     * Evidence: Browser test passed on 2025-10-01
   

2. MARK remaining checklist items:

   • Implementation Checklist: [x] any newly validated items
   • QA Checklist: [x] any newly validated items

3. ADD validation entry to Progress Log:

   - [Today]: Final validation completed
     * All 5 acceptance criteria validated ✅
     * Test coverage: 87% (exceeds 80% target)
     * Performance: All targets met
     * Security: No vulnerabilities
     * Rollback plan: Documented and verified
     * Confidence level: HIGH
     * Status: READY TO SHIP
   

4. RECORD validation results:

   • Validation timestamp
   • Confidence level
   • Risk assessment
   • Dependency status
   • Any conditions for shipping

Phase 9: Next Steps

1. DISPLAY validation outcome:

   💡 NEXT STEPS:
   ════════════════════════════════════════════════
   
   [IF READY TO SHIP:]
   ✅ Story validated and ready for production
   
   1. /sdd:story-ship [story-id]             # Deploy to production
      - Creates PR (if not created)
      - Merges to main branch
      - Moves story to completed
      - Tags release
   
   2. Post-Deployment Actions:
      - Monitor application logs
      - Watch performance metrics
      - Be ready for rollback
      - Document lessons learned
   
   [IF NEEDS WORK:]
   ⚠️ X critical issues prevent shipping
   
   1. /sdd:story-refactor [story-id]         # Return to development
   2. Address blocking issues:
      - [Issue 1]
      - [Issue 2]
   3. /sdd:story-review [story-id]           # Re-run review
   4. /sdd:story-qa [story-id]               # Re-run QA
   5. /sdd:story-validate [story-id]         # Re-validate
   
   [MONITORING COMMANDS:]
   # Laravel:
   php artisan pail                      # Watch logs in real-time
   php artisan telescope:clear           # Clear old monitoring data
   
   # System:
   tail -f storage/logs/laravel.log     # Follow application logs
   

OUTPUTS

• Updated /docs/stories/qa/[story-id].md with validation results
• Validation summary report (displayed to user)
• Updated Success Criteria with test evidence
• Updated checklists with final validation status
• Progress log entry with validation timestamp

RULES

• MUST load project context before validation
• MUST validate ALL acceptance criteria with evidence
• MUST verify 100% browser test coverage of criteria
• MUST check rollback plan is documented
• MUST assess production readiness
• SHOULD identify risks and mitigations
• SHOULD validate external dependencies
• NEVER mark story ready with failing tests
• NEVER skip acceptance criteria validation
• ALWAYS provide test evidence for each criterion
• ALWAYS update Success Criteria with validation details
• ALWAYS record confidence level in validation

Examples

Example 1: Validation Ready to Ship

INPUT:
/sdd:story-validate STORY-2025-003

OUTPUT:
→ Loading project context...
  ✓ technical-stack.md: Laravel + Pest + Playwright
  ✓ coding-standards.md: 80% coverage target
  ✓ development-process.md: Validation requirements

→ Loading story requirements...
  ✓ Story: STORY-2025-003 - Dark Mode Toggle
  ✓ Success Criteria: 5 criteria
  ✓ Implementation Checklist: 9/9 complete
  ✓ QA Checklist: 6/6 complete

→ Validating acceptance criteria...
  ✓ [1/5] User can toggle dark mode
    → tests/Browser/DarkModeTest.php::line 45 ✅
  ✓ [2/5] Theme persists across sessions
    → tests/Browser/DarkModeTest.php::line 67 ✅
  ✓ [3/5] All UI components support both themes
    → tests/Browser/DarkModeTest.php::line 89 ✅
  ✓ [4/5] Keyboard shortcut works
    → tests/Browser/DarkModeTest.php::line 112 ✅
  ✓ [5/5] Preference syncs across tabs
    → tests/Browser/DarkModeTest.php::line 134 ✅

→ Checking implementation completeness...
  ✓ Feature implementation: Complete
  ✓ Unit tests: 87% coverage (target: 80%)
  ✓ Browser tests: 100% criteria coverage
  ✓ All tests passing: 76/76

→ Verifying rollback plan...
  ✓ Rollback plan documented
  ✓ Migrations are reversible

→ Final production readiness checks...
  ✓ All acceptance criteria met
  ✓ All tests passing
  ✓ Code reviewed
  ✓ Documentation complete
  ✓ Performance acceptable
  ✓ Security verified
  ✓ Rollback plan ready

📄 VALIDATION SUMMARY
════════════════════════════════════════════════
Story: STORY-2025-003 - Dark Mode Toggle
Validated: 2025-10-01 17:45:23

RESULT: ✅ READY TO SHIP

Passed Criteria: 5/5 (100%)
Test Coverage: 87%
Quality Score: 9.2/10

CONFIDENCE LEVEL: ✅ HIGH

💡 NEXT STEPS:
════════════════════════════════════════════════
✅ Story validated and ready for production

1. /sdd:story-ship STORY-2025-003             # Deploy to production
2. Monitor application after deployment
3. Be ready to execute rollback if needed

Example 2: Validation with Blocking Issues

INPUT:
/sdd:story-validate STORY-2025-004

OUTPUT:
→ Loading project context...
  ✓ technical-stack.md loaded

→ Loading story requirements...
  ✓ Story: STORY-2025-004 - Notification System
  ✓ Success Criteria: 4 criteria

→ Validating acceptance criteria...
  ✓ [1/4] Notifications appear on events
    → tests/Browser/NotificationTest.php::line 23 ✅
  ✓ [2/4] Notifications can be dismissed
    → tests/Browser/NotificationTest.php::line 45 ✅
  ✗ [3/4] Notifications persist across sessions
    → NO BROWSER TEST FOUND ❌
  ✗ [4/4] Email notifications sent
    → NO BROWSER TEST FOUND ❌

→ Checking rollback plan...
  ✗ Rollback plan not documented

📄 VALIDATION SUMMARY
════════════════════════════════════════════════
Story: STORY-2025-004 - Notification System
Validated: 2025-10-01 18:12:45

RESULT: ⚠️ NEEDS WORK

Passed Criteria: 2/4 (50%)
Test Coverage: 78% (below 80% target)

❌ BLOCKING ISSUES:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Acceptance criterion "Notifications persist across sessions" not validated
   → Create browser test in tests/Browser/NotificationTest.php

2. Acceptance criterion "Email notifications sent" not validated
   → Create browser test for email sending

3. Rollback plan not documented
   → Add rollback steps to story file

4. Test coverage 78% below target 80%
   → Add tests to increase coverage

💡 NEXT STEPS:
════════════════════════════════════════════════
⚠️ 4 critical issues prevent shipping

1. /sdd:story-refactor STORY-2025-004         # Return to development
2. Address blocking issues:
   - Add browser test for session persistence
   - Add browser test for email notifications
   - Document rollback plan
   - Increase test coverage to 80%+
3. /sdd:story-review STORY-2025-004           # Re-run review
4. /sdd:story-qa STORY-2025-004               # Re-run QA
5. /sdd:story-validate STORY-2025-004         # Re-validate

Example 3: Validation with Warnings (Still Ship-Ready)

INPUT:
/sdd:story-validate

OUTPUT:
→ Detecting story from current branch...
  ✓ Current branch: feature/STORY-2025-005-search
  ✓ Story ID: STORY-2025-005

→ Loading story requirements...
  ✓ Success Criteria: 3 criteria

→ Validating acceptance criteria...
  ✓ All 3 criteria validated by browser tests

→ Assessing risks...
  ⚠️ Database migration changes column type
  ⚠️ Bundle size increased by 15KB

📄 VALIDATION SUMMARY
════════════════════════════════════════════════
Story: STORY-2025-005 - Advanced Search
Validated: 2025-10-01 19:23:11

RESULT: ✅ READY TO SHIP (with warnings)

Passed Criteria: 3/3 (100%)
Test Coverage: 91%

CONFIDENCE LEVEL: ⚠️ MEDIUM

⚠️ WARNINGS (non-blocking):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Database migration changes column type
   Risk: Potential data loss on rollback
   Mitigation: Backup database before deployment

2. Bundle size increased by 15KB
   Risk: Slightly slower page loads
   Mitigation: Monitor performance metrics

💡 NEXT STEPS:
════════════════════════════════════════════════
✅ Story validated - Ready to ship with awareness

1. /sdd:story-ship STORY-2025-005             # Deploy to production
2. Backup database before deployment
3. Monitor performance after deployment

Edge Cases

No Project Context

• DETECT missing /docs/project-context/ directory
• SUGGEST running /sdd:project-init
• OFFER to validate with basic checks
• WARN that validation will be incomplete

Story Not in QA

• CHECK if story in /docs/stories/development/ or /docs/stories/review/
• ERROR: "Story must complete QA before validation"
• PROVIDE workflow guidance to reach QA stage
• SUGGEST appropriate command

Missing Browser Tests

• DETECT acceptance criteria without browser test evidence
• COUNT uncovered criteria
• BLOCK validation if coverage < 100%
• PROVIDE test file examples for stack

Incomplete Checklists

• DETECT unchecked items in Implementation/QA checklists
• LIST incomplete items
• ASSESS if items are truly incomplete or just not checked
• WARN if critical items unchecked

Rollback Plan Empty

• DETECT missing or minimal rollback plan
• SUGGEST rollback steps based on git diff
• OFFER to auto-generate basic rollback plan
• WARN that deployment without rollback plan is risky

External Dependencies Not Ready

• DETECT external dependencies in story
• CHECK if dependencies are ready (if possible)
• WARN about deployment risks
• SUGGEST coordinating with dependency owners

Error Handling

• Missing /docs/project-context/: Suggest /sdd:project-init, offer basic validation
• Story not in QA: Provide clear workflow, suggest correct command
• Missing tests: Block validation, provide test creation guidance
• Git errors: Validate git state, suggest resolution
• File read errors: Report specific file issue, suggest fix

Performance Considerations

• Validation is primarily file reading and analysis (fast)
• Browser test evidence lookup is file-based (< 1s typically)
• No expensive operations unless re-running tests
• Cache story file contents for session

Related Commands

• /sdd:story-qa [id] - Must complete before validation
• /sdd:story-ship [id] - Run after validation passes
• /sdd:story-refactor [id] - Return to development if validation fails
• /sdd:story-status [id] - Check current story state

Constraints

• ✅ MUST load project context for validation standards
• ✅ MUST validate ALL acceptance criteria with evidence
• ✅ MUST verify 100% browser test coverage
• ✅ MUST check rollback plan exists
• ✅ MUST assess production readiness
• ⚠️ NEVER mark story ready with incomplete criteria validation
• ⚠️ NEVER skip browser test evidence requirement
• 📋 SHOULD identify and document risks
• 🔧 SHOULD validate external dependencies
• 💾 MUST update Success Criteria with validation details
• 🚫 BLOCK shipping if critical issues found