From b708a8d361a5ee6816982a9fad088a1cc0577d23 Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Thu, 15 Jan 2026 00:04:29 -0600
Subject: [PATCH] feat: add requirements traceability to roadmap and plan-phase

- Roadmap template now includes Requirements: field for each phase
- plan-phase loads REQUIREMENTS.md and extracts phase-specific requirements
- define-requirements shows full list inline before commit (not just counts)
---
 commands/gsd/plan-phase.md         | 14 ++++++++++++++
 get-shit-done/templates/roadmap.md |  4 ++++
 2 files changed, 18 insertions(+)

diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md
index d9cfe7bac..213d46ec8 100644
--- a/commands/gsd/plan-phase.md
+++ b/commands/gsd/plan-phase.md
@@ -39,6 +39,20 @@ Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not pr
 **Load roadmap:**
 @.planning/ROADMAP.md
 
+**Load requirements:**
+@.planning/REQUIREMENTS.md
+
+After loading, extract the requirements for the current phase:
+1. Find the phase in ROADMAP.md, get its `Requirements:` list (e.g., "PROF-01, PROF-02, PROF-03")
+2. Look up each REQ-ID in REQUIREMENTS.md to get the full description
+3. Present the requirements this phase must satisfy:
+   ```
+   Phase [N] Requirements:
+   - 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)
+   ```
+
 **Load phase context if exists (created by /gsd:discuss-phase):**
 Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
 
diff --git a/get-shit-done/templates/roadmap.md b/get-shit-done/templates/roadmap.md
index 5e7a9bf4f..ae90932e0 100644
--- a/get-shit-done/templates/roadmap.md
+++ b/get-shit-done/templates/roadmap.md
@@ -38,6 +38,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 ### Phase 1: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Nothing (first phase)
+**Requirements**: [REQ-01, REQ-02, REQ-03]
 **Research**: Unlikely (established patterns)
 **Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
 
@@ -49,6 +50,7 @@ Plans:
 ### Phase 2: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 1
+**Requirements**: [REQ-04, REQ-05]
 **Research**: Likely (new integration)
 **Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
@@ -68,6 +70,7 @@ Plans:
 ### Phase 3: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 2
+**Requirements**: [REQ-06, REQ-07, REQ-08]
 **Research**: Likely (external API)
 **Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
@@ -79,6 +82,7 @@ Plans:
 ### Phase 4: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 3
+**Requirements**: [REQ-09, REQ-10]
 **Research**: Unlikely (internal patterns)
 **Plans**: [Number of plans]