gh-sjnims-requirements-expert-plugins-requirements-expert/commands/review.md

name, description, allowed-tools

name	description	allowed-tools
re:review	Validate requirements for completeness, consistency, quality, and traceability	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