zhongwei/gh-ninthspace-claude-code-marketplace-sdd

Files

Zhongwei Li d97a70be33 Initial commit

2025-11-30 08:44:27 +08:00

24 KiB

Raw Permalink Blame History

/sdd:story-validate

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

CHECK if /docs/project-context/ directory exists
IF missing:
- SUGGEST running /sdd:project-init first
- EXIT with initialization guidance
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

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

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

3.2 Validate Each Criterion

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]

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

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

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

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

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

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

CHECK non-functional items:

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

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

CHECK if Rollback Plan section is populated
IF empty or minimal:
- WARN: "Rollback plan should be documented"
- SUGGEST rollback steps based on changes
- OFFER to populate from git diff
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
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

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]

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

IDENTIFY remaining risks:

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

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

CHECK external dependencies:

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

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

COMPILE all validation results
DETERMINE overall status:
- ✅ READY TO SHIP: All checks pass, high confidence
- ⚠️ NEEDS WORK: Critical items missing or failing
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

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

MARK remaining checklist items:
- Implementation Checklist: [x] any newly validated items
- QA Checklist: [x] any newly validated items

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

RECORD validation results:
- Validation timestamp
- Confidence level
- Risk assessment
- Dependency status
- Any conditions for shipping

Phase 9: Next Steps

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

/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

24 KiB Raw Permalink Blame History