Initial commit

2025-11-30 08:57:33 +08:00
commit b4a8193ca4
28 changed files with 7229 additions and 0 deletions
--- a/commands/review.md
+++ b/commands/review.md
@@ -0,0 +1,270 @@
+---
+name: re:review
+description: Validate requirements for completeness, consistency, quality, and traceability
+allowed-tools: [Bash, Read]
+---
+
+# Review & Validate Requirements
+
+Comprehensive validation of requirements at all levels (vision, epics, stories, tasks) checking for completeness, consistency, quality, and traceability.
+
+## Instructions
+
+Load the **requirements-validator** agent OR implement validation logic directly.
+
+### Step 1: Scan Requirements
+
+1. **Retrieve All Requirements:**
+   - Use `gh project item-list [project-number] --format json`
+   - Categorize by Type: Vision, Epic, Story, Task
+   - Count items at each level
+
+2. **Check Hierarchy:**
+   - Verify vision exists (exactly 1)
+   - Verify epics link to vision
+   - Verify stories link to epics
+   - Verify tasks link to stories
+
+### Step 2: Completeness Check
+
+**Vision Level:**
+- [ ] Problem statement exists and is clear
+- [ ] Target users are defined
+- [ ] Solution overview exists
+- [ ] Success metrics are defined
+- [ ] Scope boundaries are set
+
+**Epic Level:**
+- [ ] Each epic has clear description
+- [ ] User value is articulated
+- [ ] Scope (included/excluded) is defined
+- [ ] Success criteria exist
+- [ ] All vision elements are covered by epics
+
+**Story Level:**
+- [ ] Each story follows "As a... I want... So that..." format
+- [ ] Acceptance criteria are present (minimum 3-5)
+- [ ] Stories are small enough (1-5 days estimate)
+- [ ] All epic scope is covered by stories
+
+**Task Level:**
+- [ ] Each task has clear, action-oriented title
+- [ ] Acceptance criteria are specific and testable (minimum 3-5)
+- [ ] Tasks are right-sized (2-8 hours)
+- [ ] All story acceptance criteria are covered by tasks
+
+### Step 3: Consistency Check
+
+**Traceability:**
+- [ ] Every epic links to vision
+- [ ] Every story links to an epic
+- [ ] Every task links to a story
+- [ ] No orphaned issues (items without parents)
+
+**Naming & IDs:**
+- [ ] Consistent terminology across levels
+- [ ] No duplicate or conflicting requirements
+- [ ] Labels are applied consistently
+
+**Priority Alignment:**
+- [ ] Child priorities don't exceed parent priorities
+- [ ] Dependencies respect priority order
+
+### Step 4: Quality Check (INVEST for Stories)
+
+For each user story, verify INVEST criteria:
+- [ ] **Independent**: Can be completed without depending on others
+- [ ] **Negotiable**: Details open for discussion
+- [ ] **Valuable**: Delivers clear user value
+- [ ] **Estimable**: Team can estimate size
+- [ ] **Small**: Fits in single iteration
+- [ ] **Testable**: Clear acceptance criteria
+
+### Step 5: Validation Report
+
+Generate comprehensive report:
+
+```
+# Requirements Validation Report
+
+**Generated:** [Date/Time]
+**Project:** [Project Name]
+
+## Summary
+
+| Level | Count | Complete | Issues |
+|-------|-------|----------|--------|
+| Vision | [N] | [✓/✗] | [N] |
+| Epics | [N] | [✓/✗] | [N] |
+| Stories | [N] | [✓/✗] | [N] |
+| Tasks | [N] | [✓/✗] | [N] |
+
+**Overall Status:** [✓ Pass / ⚠️ Warning / ✗ Fail]
+
+---
+
+## Critical Issues (Must Fix)
+
+[List any critical issues that prevent requirements from being actionable]
+
+### Missing Vision
+- [ ] No vision issue found - run `/re:discover-vision`
+
+### Broken Traceability
+- [ ] Epic #[num] has no parent vision
+- [ ] Story #[num] has no parent epic
+- [ ] Task #[num] has no parent story
+
+### Incomplete Requirements
+- [ ] Epic #[num] missing scope definition
+- [ ] Story #[num] has no acceptance criteria
+- [ ] Task #[num] missing acceptance criteria
+
+---
+
+## Warnings (Should Address)
+
+[List issues that should be fixed but don't block progress]
+
+### Quality Issues
+- [ ] Story #[num] too large (>5 days) - consider splitting
+- [ ] Task #[num] too vague - needs clearer description
+- [ ] Epic #[num] overlaps with Epic #[num2]
+
+### INVEST Violations
+- [ ] Story #[num] not independent (depends on #[num2])
+- [ ] Story #[num] not valuable (too technical, no user benefit)
+- [ ] Story #[num] not testable (vague acceptance criteria)
+
+### Priority Issues
+- [ ] Must Have items exceed 60% - review priorities
+- [ ] No Won't Haves defined - consider scope boundaries
+- [ ] Child priority higher than parent
+
+---
+
+## Recommendations
+
+[Actionable suggestions for improvement]
+
+1. **Add Missing Content:**
+   - Update Epic #[num] with success criteria
+   - Add acceptance criteria to Story #[num]
+
+2. **Split Large Items:**
+   - Story #[num] - suggest splitting into [X] stories
+
+3. **Clarify Vague Items:**
+   - Task #[num] - add specific technical notes
+
+4. **Fix Traceability:**
+   - Link Story #[num] to Epic #[num2]
+
+---
+
+## Next Steps
+
+Based on validation results:
+
+**If Critical Issues Found:**
+1. Fix critical issues before proceeding
+2. Re-run `/re:review` after fixes
+
+**If Only Warnings:**
+1. Address high-priority warnings
+2. Proceed with implementation
+3. Refine as you learn
+
+**If All Pass:**
+✅ Requirements are solid! Ready for implementation.
+
+---
+
+## Validation Details
+
+### Vision Validation
+[Detailed findings for vision]
+- Status: [✓ Pass / ⚠️ Warning / ✗ Fail]
+- Issues: [List]
+
+### Epic Validation
+[Detailed findings for epics]
+- Epics validated: [N]
+- Pass: [N], Warnings: [N], Fail: [N]
+- Issues: [List]
+
+### Story Validation
+[Detailed findings for stories]
+- Stories validated: [N]
+- INVEST compliance: [%]%
+- Issues: [List]
+
+### Task Validation
+[Detailed findings for tasks]
+- Tasks validated: [N]
+- Avg acceptance criteria per task: [N]
+- Issues: [List]
+```
+
+### Step 6: Offer to Fix Issues
+
+After presenting report, offer to help fix issues:
+
+```
+Would you like help fixing any of these issues?
+
+I can:
+- Update issues with missing content
+- Split large stories/tasks
+- Add missing acceptance criteria
+- Fix broken traceability links
+
+Which would you like to address first?
+```
+
+**If user wants help:**
+- For each issue, provide specific guidance or make updates
+- Update GitHub issues in GitHub Project as needed
+- Re-run validation after fixes
+
+### Step 7: Success Message
+
+Display:
+```
+✅ Requirements review complete!
+
+**Status:** [Overall status]
+**Critical Issues:** [N]
+**Warnings:** [N]
+
+[If issues found:]
+Address critical issues before proceeding with implementation.
+Use the validation report above to guide fixes.
+
+[If no issues:]
+Requirements look good! You're ready to start implementation.
+
+**Recommendations:**
+- Re-run `/re:review` periodically (weekly/monthly)
+- Update requirements as you learn during implementation
+- Use feedback from testing to refine acceptance criteria
+
+**Next Steps:**
+[Based on validation status, suggest appropriate next actions]
+```
+
+## Error Handling
+
+- If no requirements exist: Guide to appropriate creation commands
+- If project doesn't exist: Suggest `/re:init`
+- If validation fails: Provide clear, actionable guidance
+
+## Notes
+
+- Validation checks all levels: vision, epics, stories, tasks
+- Focus on actionable findings
+- Distinguish critical issues from warnings
+- Provide specific guidance for each issue type
+- Offer to help fix issues automatically where possible
+- Can be run at any time - recommended weekly/monthly
+- Use as quality gate before sprint planning or releases