feat: add define-requirements command for scoped v1 requirements
Adds /gsd:define-requirements to transform research findings into checkable requirements before roadmap creation. New flow: new-project → research-project → define-requirements → create-roadmap New files: - commands/gsd/define-requirements.md - get-shit-done/workflows/define-requirements.md - get-shit-done/templates/requirements.md Modified: - new-project.md: updated next steps - research-project.md: points to define-requirements - create-roadmap.md: requires REQUIREMENTS.md, validates coverage - workflows/create-roadmap.md: maps phases to requirements, updates traceability Key changes: - Phases now map to specific requirement IDs - 100% requirement coverage required before roadmap creation - REQUIREMENTS.md traceability section tracks phase assignments Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -1,6 +1,10 @@
|
||||
<purpose>
|
||||
Define the phases of implementation. Each phase is a coherent chunk of work
|
||||
that delivers value. The roadmap provides structure, not detailed tasks.
|
||||
that delivers value. Phases map to requirements — every v1 requirement must
|
||||
belong to exactly one phase.
|
||||
|
||||
The roadmap provides structure, not detailed tasks. But it ensures no
|
||||
requirements are orphaned and validates coverage before planning begins.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
@@ -8,12 +12,43 @@ that delivers value. The roadmap provides structure, not detailed tasks.
|
||||
|
||||
1. ~/.claude/get-shit-done/templates/roadmap.md
|
||||
2. ~/.claude/get-shit-done/templates/state.md
|
||||
3. Read `.planning/PROJECT.md` if it exists
|
||||
4. Read `.planning/research/SUMMARY.md` if it exists
|
||||
3. ~/.claude/get-shit-done/templates/requirements.md
|
||||
4. .planning/PROJECT.md
|
||||
5. .planning/REQUIREMENTS.md
|
||||
6. .planning/research/SUMMARY.md (if exists)
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_requirements">
|
||||
Load and parse REQUIREMENTS.md:
|
||||
|
||||
```bash
|
||||
cat .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
Extract:
|
||||
- All v1 requirement IDs (AUTH-01, CONT-02, etc.)
|
||||
- Requirement categories (Authentication, Content, Social, etc.)
|
||||
- Total count of v1 requirements
|
||||
|
||||
```
|
||||
Requirements loaded:
|
||||
|
||||
Categories: [N]
|
||||
- Authentication: [X] requirements
|
||||
- Content: [Y] requirements
|
||||
- Social: [Z] requirements
|
||||
...
|
||||
|
||||
Total v1 requirements: [N]
|
||||
|
||||
All requirements must map to exactly one phase.
|
||||
```
|
||||
|
||||
**Track requirement IDs** — will verify coverage after phase identification.
|
||||
</step>
|
||||
|
||||
<step name="check_brief">
|
||||
```bash
|
||||
cat .planning/PROJECT.md 2>/dev/null || echo "No brief found"
|
||||
@@ -115,16 +150,29 @@ Select (comma-separate for multiple):
|
||||
</step>
|
||||
|
||||
<step name="identify_phases">
|
||||
Derive phases from the actual work needed.
|
||||
Derive phases from requirements. Each phase covers a coherent set of requirements.
|
||||
|
||||
**If research exists (.planning/research/SUMMARY.md):**
|
||||
- Start with suggested phases from research
|
||||
- Validate against PROJECT.md requirements
|
||||
- Adjust based on domain expertise (if any)
|
||||
- Research already identified dependencies and pitfalls — use them
|
||||
**Primary input: REQUIREMENTS.md**
|
||||
- Group requirements by natural delivery boundaries
|
||||
- Each phase should complete one or more requirement categories
|
||||
- Dependencies between requirements inform phase ordering
|
||||
|
||||
**If no research:**
|
||||
- Derive phases from PROJECT.md and domain expertise only
|
||||
**Secondary inputs:**
|
||||
- Research SUMMARY.md (if exists): suggested phases, architecture patterns
|
||||
- Domain expertise: established patterns for this type of project
|
||||
|
||||
**Phase identification process:**
|
||||
|
||||
1. Group requirements by category (Authentication, Content, Social, etc.)
|
||||
2. Identify dependencies between categories (Social needs Content, Content needs Auth)
|
||||
3. Create phases that complete entire categories where possible
|
||||
4. Split large categories across phases if needed (e.g., basic auth vs. advanced auth)
|
||||
5. Assign every v1 requirement to exactly one phase
|
||||
|
||||
**For each phase, record:**
|
||||
- Phase name and goal
|
||||
- Which requirement IDs it covers (e.g., AUTH-01, AUTH-02, AUTH-03)
|
||||
- Dependencies on other phases
|
||||
|
||||
**Check depth setting:**
|
||||
```bash
|
||||
@@ -200,6 +248,44 @@ Common phase patterns:
|
||||
- Infrastructure → Backend → Frontend → Integration
|
||||
</step>
|
||||
|
||||
<step name="validate_coverage">
|
||||
**Verify all v1 requirements are mapped to exactly one phase.**
|
||||
|
||||
Compare assigned requirements against full list from load_requirements step:
|
||||
|
||||
```
|
||||
Requirement Coverage:
|
||||
|
||||
✓ AUTH-01 → Phase 1
|
||||
✓ AUTH-02 → Phase 1
|
||||
✓ AUTH-03 → Phase 1
|
||||
✓ AUTH-04 → Phase 1
|
||||
✓ PROF-01 → Phase 2
|
||||
✓ PROF-02 → Phase 2
|
||||
...
|
||||
|
||||
Coverage: [X]/[Y] requirements mapped
|
||||
```
|
||||
|
||||
**If any requirements unmapped:**
|
||||
|
||||
```
|
||||
⚠️ Orphaned requirements (not in any phase):
|
||||
|
||||
- NOTF-01: User receives in-app notifications
|
||||
- NOTF-02: User receives email for new followers
|
||||
|
||||
These v1 requirements have no phase. Options:
|
||||
1. Add phase to cover them
|
||||
2. Move to v2 (update REQUIREMENTS.md)
|
||||
3. Assign to existing phase
|
||||
```
|
||||
|
||||
Use AskUserQuestion to resolve orphaned requirements.
|
||||
|
||||
**Do not proceed until coverage = 100%.**
|
||||
</step>
|
||||
|
||||
<step name="detect_research_needs">
|
||||
**For each phase, determine if research is likely needed.**
|
||||
|
||||
@@ -343,6 +429,14 @@ Write to `.planning/ROADMAP.md` with:
|
||||
- Domain Expertise section (paths from detect_domain step, or "None" if skipped)
|
||||
- Phase list with names and one-line descriptions
|
||||
- Dependencies (what must complete before what)
|
||||
- **Requirement mappings** (which REQ-IDs each phase covers):
|
||||
```markdown
|
||||
### Phase 1: Authentication
|
||||
**Goal**: Secure user authentication
|
||||
**Depends on**: Nothing (first phase)
|
||||
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
|
||||
**Research**: Unlikely (established patterns)
|
||||
```
|
||||
- **Research flags** (from detect_research_needs step):
|
||||
- `Research: Likely ([reason])` with `Research topics:` for flagged phases
|
||||
- `Research: Unlikely ([reason])` for unflagged phases
|
||||
@@ -358,6 +452,32 @@ mkdir -p .planning/phases/02-{phase-name}
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_requirements_traceability">
|
||||
Update REQUIREMENTS.md traceability section with phase mappings:
|
||||
|
||||
Read current REQUIREMENTS.md and update the Traceability table:
|
||||
|
||||
```markdown
|
||||
## Traceability
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| AUTH-01 | Phase 1 | Pending |
|
||||
| AUTH-02 | Phase 1 | Pending |
|
||||
| AUTH-03 | Phase 1 | Pending |
|
||||
| AUTH-04 | Phase 1 | Pending |
|
||||
| PROF-01 | Phase 2 | Pending |
|
||||
...
|
||||
|
||||
**Coverage:**
|
||||
- v1 requirements: [X] total
|
||||
- Mapped to phases: [X]
|
||||
- Unmapped: 0 ✓
|
||||
```
|
||||
|
||||
Write updated REQUIREMENTS.md.
|
||||
</step>
|
||||
|
||||
<step name="initialize_project_state">
|
||||
|
||||
Create STATE.md — the project's living memory.
|
||||
@@ -436,27 +556,27 @@ Resume file: None
|
||||
</step>
|
||||
|
||||
<step name="git_commit_initialization">
|
||||
Commit project initialization (brief + roadmap + state together):
|
||||
Commit roadmap with requirement mappings:
|
||||
|
||||
```bash
|
||||
git add .planning/PROJECT.md .planning/ROADMAP.md .planning/STATE.md
|
||||
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
|
||||
git add .planning/phases/
|
||||
# config.json if exists
|
||||
git add .planning/config.json 2>/dev/null
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: initialize [project-name] ([N] phases)
|
||||
docs: create roadmap ([N] phases, [X] requirements)
|
||||
|
||||
[One-liner from PROJECT.md]
|
||||
|
||||
Phases:
|
||||
1. [phase-name]: [goal]
|
||||
2. [phase-name]: [goal]
|
||||
3. [phase-name]: [goal]
|
||||
1. [phase-name]: [requirements covered]
|
||||
2. [phase-name]: [requirements covered]
|
||||
3. [phase-name]: [requirements covered]
|
||||
|
||||
All v1 requirements mapped to phases.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: docs: initialize [project] ([N] phases)"
|
||||
Confirm: "Committed: docs: create roadmap ([N] phases, [X] requirements)"
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
@@ -512,9 +632,12 @@ Phases are buckets of work, not project management artifacts.
|
||||
|
||||
<success_criteria>
|
||||
Roadmap is complete when:
|
||||
- [ ] `.planning/ROADMAP.md` exists
|
||||
- [ ] REQUIREMENTS.md loaded and parsed
|
||||
- [ ] All v1 requirements mapped to exactly one phase (100% coverage)
|
||||
- [ ] `.planning/ROADMAP.md` exists with requirement mappings
|
||||
- [ ] `.planning/STATE.md` exists (project memory initialized)
|
||||
- [ ] Phases defined with clear names (count derived from work, not imposed)
|
||||
- [ ] REQUIREMENTS.md traceability section updated
|
||||
- [ ] Phases defined with clear names (count derived from requirements, not imposed)
|
||||
- [ ] **Research flags assigned** (Likely/Unlikely for each phase)
|
||||
- [ ] **Research topics listed** for Likely phases
|
||||
- [ ] Phase directories created
|
||||
|
||||
257
get-shit-done/workflows/define-requirements.md
Normal file
257
get-shit-done/workflows/define-requirements.md
Normal file
@@ -0,0 +1,257 @@
|
||||
<purpose>
|
||||
Transform research findings into scoped, checkable requirements.
|
||||
|
||||
Research tells you what products in this domain typically have.
|
||||
Requirements tell you what YOU are building for v1.
|
||||
|
||||
This is the bridge between "what's possible" and "what we're committing to."
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
**Read these files NOW:**
|
||||
|
||||
1. ~/.claude/get-shit-done/templates/requirements.md
|
||||
2. .planning/PROJECT.md
|
||||
3. .planning/research/FEATURES.md
|
||||
4. .planning/research/SUMMARY.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_context">
|
||||
Read PROJECT.md and extract:
|
||||
- Core value (the ONE thing that must work)
|
||||
- Stated constraints (budget, timeline, tech limitations)
|
||||
- Any explicit scope boundaries from project definition
|
||||
|
||||
Read research/FEATURES.md and extract:
|
||||
- Table stakes (users expect these)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (commonly requested, often problematic)
|
||||
- Feature dependencies
|
||||
- MVP vs full product recommendations
|
||||
|
||||
Read research/SUMMARY.md for:
|
||||
- Overall confidence level
|
||||
- Key architectural constraints
|
||||
- Suggested phase structure (informational only)
|
||||
</step>
|
||||
|
||||
<step name="present_features">
|
||||
Present researched features grouped by category:
|
||||
|
||||
```
|
||||
Based on research, here are the features for [domain]:
|
||||
|
||||
## Authentication
|
||||
**Table stakes:**
|
||||
- Sign up with email/password
|
||||
- Email verification
|
||||
- Password reset
|
||||
- Session management
|
||||
|
||||
**Differentiators:**
|
||||
- Magic link login
|
||||
- OAuth (Google, GitHub)
|
||||
- 2FA
|
||||
|
||||
**Research notes:** [any relevant notes from FEATURES.md]
|
||||
|
||||
---
|
||||
|
||||
## [Next Category]
|
||||
...
|
||||
```
|
||||
|
||||
For each category, include:
|
||||
- Table stakes from FEATURES.md
|
||||
- Differentiators from FEATURES.md
|
||||
- Any anti-features flagged (with warnings)
|
||||
- Complexity notes where relevant
|
||||
</step>
|
||||
|
||||
<step name="scope_categories">
|
||||
For each category, use AskUserQuestion:
|
||||
|
||||
- header: "[Category name]"
|
||||
- question: "Which [category] features are in v1?"
|
||||
- multiSelect: true
|
||||
- options:
|
||||
- "[Feature 1]" — [brief description or complexity note]
|
||||
- "[Feature 2]" — [brief description]
|
||||
- "[Feature 3]" — [brief description]
|
||||
- "None for v1" — Defer entire category
|
||||
|
||||
Repeat for each category from research.
|
||||
|
||||
**Track responses:**
|
||||
- Selected features → v1 requirements
|
||||
- Unselected table stakes → flag as v2 (users expect these)
|
||||
- Unselected differentiators → out of scope (unless user specifies v2)
|
||||
</step>
|
||||
|
||||
<step name="identify_gaps">
|
||||
After scoping all researched categories, ask for additions:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Additions"
|
||||
- question: "Any requirements research missed? (Features specific to your vision)"
|
||||
- options:
|
||||
- "No, research covered it" — Proceed to generate
|
||||
- "Yes, let me add some" — Capture additional requirements
|
||||
|
||||
**If "Yes":**
|
||||
|
||||
Ask inline (freeform): "What additional requirements do you need?"
|
||||
|
||||
Parse response into requirement format and add to v1 list.
|
||||
</step>
|
||||
|
||||
<step name="validate_core_value">
|
||||
Cross-check requirements against Core Value from PROJECT.md:
|
||||
|
||||
```
|
||||
Core value: "[from PROJECT.md]"
|
||||
|
||||
Requirements that directly support core value:
|
||||
- [requirement 1]
|
||||
- [requirement 2]
|
||||
|
||||
⚠️ Warning: Core value may not be fully covered by selected requirements.
|
||||
Missing coverage: [gap description]
|
||||
```
|
||||
|
||||
**If gap detected:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Core value"
|
||||
- question: "Core value '[X]' may need additional requirements. Add coverage?"
|
||||
- options:
|
||||
- "Yes, suggest requirements" — Claude suggests, user confirms
|
||||
- "No, it's covered" — Proceed
|
||||
- "Adjust core value" — User provides updated core value
|
||||
</step>
|
||||
|
||||
<step name="generate_requirements">
|
||||
Create `.planning/REQUIREMENTS.md` using template.
|
||||
|
||||
**Structure:**
|
||||
- Header with project name and date
|
||||
- v1 Requirements grouped by category (checkboxes)
|
||||
- v2 Requirements (deferred, no checkboxes yet)
|
||||
- Out of Scope (explicit exclusions with reasoning)
|
||||
- Traceability section (empty, filled by create-roadmap)
|
||||
|
||||
**Requirement format:**
|
||||
```markdown
|
||||
### [Category]
|
||||
|
||||
- [ ] **[REQ-ID]**: [Requirement description]
|
||||
- [ ] **[REQ-ID]**: [Requirement description]
|
||||
```
|
||||
|
||||
**REQ-ID format:** `[CATEGORY]-[NUMBER]`
|
||||
- AUTH-01, AUTH-02
|
||||
- CONTENT-01, CONTENT-02
|
||||
- SOCIAL-01, SOCIAL-02
|
||||
|
||||
IDs enable traceability from roadmap phases.
|
||||
</step>
|
||||
|
||||
<step name="summarize">
|
||||
Present summary before committing:
|
||||
|
||||
```
|
||||
## Requirements Summary
|
||||
|
||||
**v1 Scope:**
|
||||
- Authentication: [N] requirements
|
||||
- [Category]: [N] requirements
|
||||
- [Category]: [N] requirements
|
||||
Total: [X] requirements
|
||||
|
||||
**v2 (Deferred):**
|
||||
- [Category]: [N] requirements
|
||||
Total: [Y] requirements
|
||||
|
||||
**Out of Scope:**
|
||||
- [Feature]: [reason]
|
||||
- [Feature]: [reason]
|
||||
|
||||
**Core Value Alignment:** ✓ Covered / ⚠️ Gaps noted
|
||||
|
||||
---
|
||||
|
||||
Does this capture what you're building? (yes / adjust)
|
||||
```
|
||||
|
||||
If "adjust": Return to scope_categories or identify_gaps as appropriate.
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit requirements:
|
||||
|
||||
```bash
|
||||
git add .planning/REQUIREMENTS.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: define v1 requirements
|
||||
|
||||
[X] requirements across [N] categories.
|
||||
[Y] requirements deferred to v2.
|
||||
|
||||
Core value: [from PROJECT.md]
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Requirements defined:
|
||||
|
||||
- Requirements: .planning/REQUIREMENTS.md
|
||||
- v1 scope: [X] requirements across [N] categories
|
||||
- v2 deferred: [Y] requirements
|
||||
- Out of scope: [Z] exclusions
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create roadmap** — phases mapped to requirements
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<quality_criteria>
|
||||
**Good requirements:**
|
||||
- Specific and testable ("User can reset password via email link")
|
||||
- User-centric ("User can X" not "System does Y")
|
||||
- Atomic (one capability per requirement)
|
||||
- Independent where possible (minimal dependencies)
|
||||
|
||||
**Bad requirements:**
|
||||
- Vague ("Handle authentication")
|
||||
- Technical implementation ("Use bcrypt for passwords")
|
||||
- Compound ("User can login and manage profile and change settings")
|
||||
- Dependent on unstated assumptions
|
||||
</quality_criteria>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md core value extracted
|
||||
- [ ] Research FEATURES.md loaded and parsed
|
||||
- [ ] All categories presented to user
|
||||
- [ ] User scoped each category (v1/v2/out of scope)
|
||||
- [ ] User had opportunity to add requirements
|
||||
- [ ] Core value alignment validated
|
||||
- [ ] REQUIREMENTS.md created with REQ-IDs
|
||||
- [ ] v1, v2, and out of scope clearly separated
|
||||
- [ ] Requirements committed to git
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user