From d0488c503f4ab3528e3ac54ab2ac875d74db99b7 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 23:25:41 -0600 Subject: [PATCH] feat: add define-requirements command for scoped v1 requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- commands/gsd/create-roadmap.md | 20 +- commands/gsd/define-requirements.md | 110 ++++++++ commands/gsd/new-project.md | 20 +- commands/gsd/research-project.md | 10 +- get-shit-done/templates/requirements.md | 231 ++++++++++++++++ get-shit-done/workflows/create-roadmap.md | 167 ++++++++++-- .../workflows/define-requirements.md | 257 ++++++++++++++++++ 7 files changed, 777 insertions(+), 38 deletions(-) create mode 100644 commands/gsd/define-requirements.md create mode 100644 get-shit-done/templates/requirements.md create mode 100644 get-shit-done/workflows/define-requirements.md diff --git a/commands/gsd/create-roadmap.md b/commands/gsd/create-roadmap.md index 38bf97d3a..a99647cb0 100644 --- a/commands/gsd/create-roadmap.md +++ b/commands/gsd/create-roadmap.md @@ -12,7 +12,9 @@ allowed-tools: Create project roadmap with phase breakdown. -Roadmaps define what work happens in what order. Run after /gsd:new-project. +Roadmaps define what work happens in what order. Phases map to requirements. + +Run after `/gsd:define-requirements`. @@ -24,6 +26,7 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project. @.planning/PROJECT.md @.planning/config.json +@.planning/REQUIREMENTS.md @.planning/research/SUMMARY.md (if exists) @@ -33,6 +36,9 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project. ```bash # Verify project exists [ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; } + +# Verify requirements exist +[ -f .planning/REQUIREMENTS.md ] || { echo "ERROR: No REQUIREMENTS.md found. Run /gsd:define-requirements first."; exit 1; } ``` @@ -61,12 +67,15 @@ If "Replace": Continue with workflow Follow the create-roadmap.md workflow starting from detect_domain step. The workflow handles: +- Loading requirements - Domain expertise detection -- Phase identification +- Phase identification mapped to requirements +- Requirement coverage validation (no orphaned requirements) - Research flags for each phase - Confirmation gates (respecting config mode) -- ROADMAP.md creation +- ROADMAP.md creation with requirement mappings - STATE.md initialization +- REQUIREMENTS.md traceability update - Phase directory creation - Git commit @@ -109,8 +118,11 @@ Roadmap created: - [ ] PROJECT.md validated -- [ ] ROADMAP.md created with phases +- [ ] REQUIREMENTS.md validated +- [ ] All v1 requirements mapped to phases (no orphans) +- [ ] ROADMAP.md created with phases and requirement mappings - [ ] STATE.md initialized +- [ ] REQUIREMENTS.md traceability section updated - [ ] Phase directories created - [ ] Changes committed diff --git a/commands/gsd/define-requirements.md b/commands/gsd/define-requirements.md new file mode 100644 index 000000000..c7b1043d1 --- /dev/null +++ b/commands/gsd/define-requirements.md @@ -0,0 +1,110 @@ +--- +name: gsd:define-requirements +description: Define what "done" looks like with checkable requirements +allowed-tools: + - Read + - Write + - Bash + - Glob + - AskUserQuestion +--- + + +Define concrete, checkable requirements from research findings. + +Research answers "what do products like this have?" +Requirements answers "what are WE building?" + +Transforms research features into scoped v1/v2 requirements that roadmap phases map to. + +Run after `/gsd:research-project`, before `/gsd:create-roadmap`. + +Output: `.planning/REQUIREMENTS.md` + + + +@~/.claude/get-shit-done/workflows/define-requirements.md +@~/.claude/get-shit-done/templates/requirements.md + + + +@.planning/PROJECT.md +@.planning/research/FEATURES.md (required) +@.planning/research/SUMMARY.md + + + + + +```bash +# Verify project exists +[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; } + +# Verify research exists +[ -f .planning/research/FEATURES.md ] || { echo "ERROR: No research found. Run /gsd:research-project first."; exit 1; } + +# Check if requirements already exist +[ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS" +``` + + + +**If REQUIREMENTS_EXISTS:** + +Use AskUserQuestion: +- header: "Requirements exist" +- question: "Requirements already defined. What would you like to do?" +- options: + - "View existing" — Show current requirements + - "Replace" — Define requirements fresh (will overwrite) + - "Cancel" — Keep existing requirements + +If "View existing": Read and display `.planning/REQUIREMENTS.md`, then exit +If "Cancel": Exit +If "Replace": Continue with workflow + + + +Follow the define-requirements.md workflow: +- Load research features +- Present features by category +- Ask user to scope each category (v1 / v2 / out of scope) +- Capture any additions research missed +- Generate REQUIREMENTS.md with checkable list + + + +``` +Requirements defined: + +- Requirements: .planning/REQUIREMENTS.md +- v1 scope: [N] requirements across [M] categories +- v2 scope: [X] requirements deferred +- Out of scope: [Y] requirements excluded + +--- + +## ▶ Next Up + +**Create roadmap** — phases mapped to requirements + +`/gsd:create-roadmap` + +`/clear` first → fresh context window + +--- +``` + + + + + +- [ ] PROJECT.md validated +- [ ] Research FEATURES.md loaded +- [ ] Features presented by category +- [ ] User scoped each category (v1/v2/out of scope) +- [ ] User had opportunity to add missing requirements +- [ ] REQUIREMENTS.md created with checkable list +- [ ] Requirements committed to git +- [ ] User knows next step (create-roadmap) + diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md index 56f7631be..f30a20c70 100644 --- a/commands/gsd/new-project.md +++ b/commands/gsd/new-project.md @@ -303,20 +303,24 @@ Project initialized: ## ▶ Next Up -Choose your path: - -**Option A: Research first** (recommended for new domains) -Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls. +**Research the domain** (recommended) `/gsd:research-project` -**Option B: Create roadmap directly** (for familiar domains) -Skip research if you know this domain well or have a clear spec. - -`/gsd:create-roadmap` +Discovers standard stacks, expected features, architecture patterns, and common pitfalls. Then define requirements and create roadmap. `/clear` first → fresh context window +**Full flow:** research-project → define-requirements → create-roadmap + +--- + +**Skip research** (familiar domains only) + +If you know this domain well, skip directly to defining requirements: + +`/gsd:define-requirements` + --- ``` diff --git a/commands/gsd/research-project.md b/commands/gsd/research-project.md index d4fc211c7..6f406fc5a 100644 --- a/commands/gsd/research-project.md +++ b/commands/gsd/research-project.md @@ -22,7 +22,7 @@ Answers the questions that inform quality roadmaps: - How are these systems typically structured? - What do projects in this domain commonly get wrong? -Run after `/gsd:new-project`, before `/gsd:create-roadmap`. +Run after `/gsd:new-project`, before `/gsd:define-requirements`. Output: `.planning/research/` folder with ecosystem knowledge. @@ -95,12 +95,14 @@ Research complete: ## ▶ Next Up -**Create roadmap** — informed by research +**Define requirements** — scope your v1 from research findings -`/gsd:create-roadmap` +`/gsd:define-requirements` `/clear` first → fresh context window +**Flow:** research-project → **define-requirements** → create-roadmap + --- ``` @@ -130,5 +132,5 @@ Research complete: - [ ] All research documents created in .planning/research/ - [ ] SUMMARY.md includes roadmap implications - [ ] Research committed to git -- [ ] User knows next step (create-roadmap) +- [ ] User knows next step (define-requirements) diff --git a/get-shit-done/templates/requirements.md b/get-shit-done/templates/requirements.md new file mode 100644 index 000000000..685142fcd --- /dev/null +++ b/get-shit-done/templates/requirements.md @@ -0,0 +1,231 @@ +# Requirements Template + +Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done." + + + + + +**Requirement Format:** +- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03) +- Description: User-centric, testable, atomic +- Checkbox: Only for v1 requirements (v2 are not yet actionable) + +**Categories:** +- Derive from research FEATURES.md categories +- Keep consistent with domain conventions +- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin + +**v1 vs v2:** +- v1: Committed scope, will be in roadmap phases +- v2: Acknowledged but deferred, not in current roadmap +- Moving v2 → v1 requires roadmap update + +**Out of Scope:** +- Explicit exclusions with reasoning +- Prevents "why didn't you include X?" later +- Anti-features from research belong here with warnings + +**Traceability:** +- Empty initially, populated by create-roadmap +- Each requirement maps to exactly one phase +- Unmapped requirements = roadmap gap (error in create-roadmap) + +**Status Values:** +- Pending: Not started +- In Progress: Phase is active +- Complete: Requirement verified +- Blocked: Waiting on external factor + + + + + +**After each phase completes:** +1. Mark covered requirements as Complete +2. Update traceability status +3. Note any requirements that changed scope + +**After roadmap updates:** +1. Verify all v1 requirements still mapped +2. Add new requirements if scope expanded +3. Move requirements to v2/out of scope if descoped + +**Requirement completion criteria:** +- Requirement is "Complete" when: + - Feature is implemented + - Feature is verified (tests pass, manual check done) + - Feature is committed + + + + + +```markdown +# Requirements: CommunityApp + +**Defined:** 2025-01-14 +**Core Value:** Users can share and discuss content with people who share their interests + +## v1 Requirements + +### Authentication + +- [ ] **AUTH-01**: User can sign up with email and password +- [ ] **AUTH-02**: User receives email verification after signup +- [ ] **AUTH-03**: User can reset password via email link +- [ ] **AUTH-04**: User session persists across browser refresh + +### Profiles + +- [ ] **PROF-01**: User can create profile with display name +- [ ] **PROF-02**: User can upload avatar image +- [ ] **PROF-03**: User can write bio (max 500 chars) +- [ ] **PROF-04**: User can view other users' profiles + +### Content + +- [ ] **CONT-01**: User can create text post +- [ ] **CONT-02**: User can upload image with post +- [ ] **CONT-03**: User can edit own posts +- [ ] **CONT-04**: User can delete own posts +- [ ] **CONT-05**: User can view feed of posts + +### Social + +- [ ] **SOCL-01**: User can follow other users +- [ ] **SOCL-02**: User can unfollow users +- [ ] **SOCL-03**: User can like posts +- [ ] **SOCL-04**: User can comment on posts +- [ ] **SOCL-05**: User can view activity feed (followed users' posts) + +## v2 Requirements + +### Notifications + +- **NOTF-01**: User receives in-app notifications +- **NOTF-02**: User receives email for new followers +- **NOTF-03**: User receives email for comments on own posts +- **NOTF-04**: User can configure notification preferences + +### Moderation + +- **MODR-01**: User can report content +- **MODR-02**: User can block other users +- **MODR-03**: Admin can view reported content +- **MODR-04**: Admin can remove content +- **MODR-05**: Admin can ban users + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| Real-time chat | High complexity, not core to community value | +| Video posts | Storage/bandwidth costs, defer to v2+ | +| OAuth login | Email/password sufficient for v1 | +| Mobile app | Web-first, mobile later | + +## 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 | +| PROF-02 | Phase 2 | Pending | +| PROF-03 | Phase 2 | Pending | +| PROF-04 | Phase 2 | Pending | +| CONT-01 | Phase 3 | Pending | +| CONT-02 | Phase 3 | Pending | +| CONT-03 | Phase 3 | Pending | +| CONT-04 | Phase 3 | Pending | +| CONT-05 | Phase 3 | Pending | +| SOCL-01 | Phase 4 | Pending | +| SOCL-02 | Phase 4 | Pending | +| SOCL-03 | Phase 4 | Pending | +| SOCL-04 | Phase 4 | Pending | +| SOCL-05 | Phase 4 | Pending | + +**Coverage:** +- v1 requirements: 18 total +- Mapped to phases: 18 +- Unmapped: 0 ✓ + +--- +*Requirements defined: 2025-01-14* +*Last updated: 2025-01-14 after initial definition* +``` + + diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md index bcfc06d74..56b1a5be6 100644 --- a/get-shit-done/workflows/create-roadmap.md +++ b/get-shit-done/workflows/create-roadmap.md @@ -1,6 +1,10 @@ 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. @@ -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) + +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. + + ```bash cat .planning/PROJECT.md 2>/dev/null || echo "No brief found" @@ -115,16 +150,29 @@ Select (comma-separate for multiple): -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 + +**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%.** + + **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} + +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. + + Create STATE.md — the project's living memory. @@ -436,27 +556,27 @@ Resume file: None -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)" @@ -512,9 +632,12 @@ Phases are buckets of work, not project management artifacts. 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 diff --git a/get-shit-done/workflows/define-requirements.md b/get-shit-done/workflows/define-requirements.md new file mode 100644 index 000000000..002912dcd --- /dev/null +++ b/get-shit-done/workflows/define-requirements.md @@ -0,0 +1,257 @@ + +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." + + + +**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 + + + + + +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) + + + +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 + + + +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) + + + +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. + + + +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 + + + +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. + + + +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. + + + +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 +)" +``` + + + +``` +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` + +`/clear` first → fresh context window + +--- +``` + + + + + +**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 + + + +- [ ] 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 +