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:
Lex Christopherson
2026-01-14 23:25:41 -06:00
parent 53efcfbfe1
commit d0488c503f
7 changed files with 777 additions and 38 deletions

View File

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

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