zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:44:27 +08:00
commit d97a70be33
36 changed files with 17033 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

668
commands/story-validate.md Normal file
View File

@@ -0,0 +1,668 @@
# /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:
```markdown
## 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:
```markdown
## 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:
```markdown
- [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
```bash
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
```bash
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)
```bash
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