feat: enhance roadmap and planning workflows

- create-roadmap: improved phase structuring and requirements tracing - plan-phase: better task decomposition and wave assignment - roadmap.md template: cleaner format - phase-prompt.md template: structured planning prompt Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-15 09:34:48 -06:00
parent 869f02e973
commit 87909f97ae
6 changed files with 317 additions and 2 deletions
--- a/commands/gsd/create-roadmap.md
+++ b/commands/gsd/create-roadmap.md
@@ -22,6 +22,7 @@ Run after `/gsd:define-requirements`.
@~/.claude/get-shit-done/workflows/create-roadmap.md
@~/.claude/get-shit-done/templates/roadmap.md
@~/.claude/get-shit-done/templates/state.md
+@~/.claude/get-shit-done/references/goal-backward.md
 </execution_context>

 <context>
@@ -121,7 +122,9 @@ Roadmap created:
 - [ ] PROJECT.md validated
 - [ ] REQUIREMENTS.md validated
 - [ ] All v1 requirements mapped to phases (no orphans)
- [ ] ROADMAP.md created with phases and requirement mappings
+- [ ] Success criteria derived for each phase (2-5 observable behaviors)
+- [ ] Success criteria cross-checked against requirements (gaps resolved)
+- [ ] ROADMAP.md created with phases, requirement mappings, and success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability section updated
 - [ ] Phase directories created
--- a/commands/gsd/plan-phase.md
+++ b/commands/gsd/plan-phase.md
@@ -28,6 +28,7 @@ Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-na
@~/.claude/get-shit-done/references/scope-estimation.md
@~/.claude/get-shit-done/references/checkpoints.md
@~/.claude/get-shit-done/references/tdd.md
+@~/.claude/get-shit-done/references/goal-backward.md
 </execution_context>

 <context>
@@ -77,6 +78,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.

 - One or more PLAN.md files created in .planning/phases/XX-name/
 - Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
+- must_haves derived from phase goal and documented in frontmatter (truths, artifacts, key_links)
 - Tasks are specific enough for Claude to execute
 - User knows next steps (execute plan or review/adjust)
  </success_criteria>
--- a/get-shit-done/templates/phase-prompt.md
+++ b/get-shit-done/templates/phase-prompt.md
@@ -19,6 +19,12 @@ files_modified: []          # Files this plan modifies.
 autonomous: true            # false if plan has checkpoints requiring user interaction
 domain: [optional - if domain skill loaded]
 user_setup: []              # Human-required setup Claude cannot automate (see below)
+
+# Goal-backward verification (derived during planning, verified after execution)
+must_haves:
+  truths: []                # Observable behaviors that must be true for goal achievement
+  artifacts: []             # Files that must exist with real implementation
+  key_links: []             # Critical connections between artifacts
 ---

 <objective>
@@ -133,9 +139,12 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `domain` | No | Domain skill if loaded (e.g., `next-js`) |
 | `user_setup` | No | Array of human-required setup items (external services) |
+| `must_haves` | Yes | Goal-backward verification criteria (see below) |

 **Wave is pre-computed:** Wave numbers are assigned during `/gsd:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.

+**Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
+
 ---

 ## Parallel vs Sequential
@@ -497,3 +506,71 @@ user_setup:
 **Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.

 See `~/.claude/get-shit-done/templates/user-setup.md` for full schema and examples
+
+---
+
+## Must-Haves (Goal-Backward Verification)
+
+The `must_haves` field defines what must be TRUE for the phase goal to be achieved. Derived during planning, verified after execution.
+
+**Structure:**
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+    - "Messages persist across refresh"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 30
+    - path: "src/app/api/chat/route.ts"
+      provides: "Message CRUD operations"
+      exports: ["GET", "POST"]
+    - path: "prisma/schema.prisma"
+      provides: "Message model"
+      contains: "model Message"
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+      pattern: "fetch.*api/chat"
+    - from: "src/app/api/chat/route.ts"
+      to: "prisma.message"
+      via: "database query"
+      pattern: "prisma\\.message\\.(find|create)"
+```
+
+**Field descriptions:**
+
+| Field | Purpose |
+|-------|---------|
+| `truths` | Observable behaviors from user perspective. Each must be testable. |
+| `artifacts` | Files that must exist with real implementation. |
+| `artifacts[].path` | File path relative to project root. |
+| `artifacts[].provides` | What this artifact delivers. |
+| `artifacts[].min_lines` | Optional. Minimum lines to be considered substantive. |
+| `artifacts[].exports` | Optional. Expected exports to verify. |
+| `artifacts[].contains` | Optional. Pattern that must exist in file. |
+| `key_links` | Critical connections between artifacts. |
+| `key_links[].from` | Source artifact. |
+| `key_links[].to` | Target artifact or endpoint. |
+| `key_links[].via` | How they connect (description). |
+| `key_links[].pattern` | Optional. Regex to verify connection exists. |
+
+**Why this matters:**
+
+Task completion ≠ Goal achievement. A task "create chat component" can complete by creating a placeholder. The `must_haves` field captures what must actually work, enabling verification to catch gaps before they compound.
+
+**Verification flow:**
+
+1. Plan-phase derives must_haves from phase goal (goal-backward)
+2. Must_haves written to PLAN.md frontmatter
+3. Execute-phase runs all plans
+4. Verification subagent checks must_haves against codebase
+5. Gaps found → fix plans created → execute → re-verify
+6. All must_haves pass → phase complete
+
+See `~/.claude/get-shit-done/references/goal-backward.md` for derivation process.
+See `~/.claude/get-shit-done/workflows/verify-phase.md` for verification logic.
--- a/get-shit-done/templates/roadmap.md
+++ b/get-shit-done/templates/roadmap.md
@@ -39,6 +39,10 @@ Decimal phases appear between their surrounding integers in numeric order.
 **Goal**: [What this phase delivers]
 **Depends on**: Nothing (first phase)
 **Requirements**: [REQ-01, REQ-02, REQ-03]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
 **Research**: Unlikely (established patterns)
 **Plans**: [Number of plans, e.g., "3 plans" or "TBD"]

@@ -51,6 +55,9 @@ Plans:
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 1
 **Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
 **Research**: Likely (new integration)
 **Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
@@ -62,6 +69,8 @@ Plans:
 ### Phase 2.1: Critical Fix (INSERTED)
 **Goal**: [Urgent work inserted between phases]
 **Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
 **Plans**: 1 plan

 Plans:
@@ -71,6 +80,10 @@ Plans:
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 2
 **Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
 **Research**: Likely (external API)
 **Research topics**: [What needs investigating]
 **Plans**: [Number of plans]
@@ -83,6 +96,9 @@ Plans:
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 3
 **Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
 **Research**: Unlikely (internal patterns)
 **Plans**: [Number of plans]

@@ -112,6 +128,13 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning

+**Success criteria:**
+- 2-5 observable behaviors per phase (from user's perspective)
+- Cross-checked against requirements during roadmap creation
+- Flow downstream to `must_haves` in plan-phase
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
+
 **Research flags:**
 - `Research: Likely` - External APIs, new libraries, architectural decisions
 - `Research: Unlikely` - Internal patterns, CRUD operations, established conventions
--- a/get-shit-done/workflows/create-roadmap.md
+++ b/get-shit-done/workflows/create-roadmap.md
@@ -248,6 +248,97 @@ Common phase patterns:
 - Infrastructure → Backend → Frontend → Integration
  </step>

+<step name="derive_phase_success_criteria">
+**For each phase, derive what must be TRUE when it completes.**
+
+This catches scope gaps before planning begins. Requirements tell us what to build; success criteria tell us what users can do.
+
+**Process for each phase:**
+
+1. **State the phase goal** (from identify_phases)
+
+2. **Ask: "What must be TRUE for users when this phase completes?"**
+   - Think from user's perspective, not implementation
+   - 2-5 observable behaviors per phase
+   - Each should be testable/verifiable
+
+3. **Cross-check against mapped requirements:**
+   - Does each success criterion have at least one requirement supporting it?
+   - Does each requirement contribute to at least one success criterion?
+
+4. **Flag gaps:**
+   - Success criterion with no supporting requirement → Add requirement or mark as out of scope
+   - Requirement that supports no criterion → Question if it belongs in this phase
+
+**Example:**
+
+```
+Phase 2: Authentication
+Goal: Users can securely access their accounts
+
+Success Criteria (what must be TRUE):
+1. User can create account with email/password
+2. User can log in and stay logged in across browser sessions
+3. User can log out from any page
+4. User can reset forgotten password
+
+Requirements mapped: AUTH-01, AUTH-02, AUTH-03
+
+Cross-check:
+✓ Criterion 1 ← AUTH-01 (create account)
+✓ Criterion 2 ← AUTH-02 (log in) — but "stay logged in" needs session persistence
+✓ Criterion 3 ← AUTH-03 (log out)
+✗ Criterion 4 ← No requirement covers password reset
+
+Gap found: Password reset not in requirements.
+→ Add AUTH-04: User can reset password via email
+   OR mark "Password reset" as v2 scope
+```
+
+**Present to user:**
+
+```
+Phase success criteria derived:
+
+Phase 1: Foundation
+Goal: Project scaffolding and configuration
+Success criteria:
+  1. Project builds without errors
+  2. Development server runs locally
+  3. CI pipeline passes
+Requirements: SETUP-01, SETUP-02 ✓ (all criteria covered)
+
+Phase 2: Authentication
+Goal: Users can securely access their accounts
+Success criteria:
+  1. User can create account with email/password
+  2. User can log in and stay logged in across sessions
+  3. User can log out from any page
+  4. User can reset forgotten password ⚠️
+Requirements: AUTH-01, AUTH-02, AUTH-03
+Gap: Criterion 4 (password reset) has no requirement
+
+Phase 3: User Profile
+...
+
+---
+
+⚠️ 1 gap found in Phase 2
+
+Options:
+1. Add AUTH-04 for password reset
+2. Mark password reset as v2 scope
+3. Adjust success criteria
+```
+
+**Resolve all gaps before proceeding.**
+
+Success criteria flow downstream:
+- Written to ROADMAP.md (high-level, user-observable)
+- Inform `must_haves` derivation in plan-phase (concrete artifacts/wiring)
+- Verified by verify-phase after execution
+</step>
+
 <step name="validate_coverage">
 **Verify all v1 requirements are mapped to exactly one phase.**

@@ -634,7 +725,9 @@ Phases are buckets of work, not project management artifacts.
 Roadmap is complete when:
 - [ ] REQUIREMENTS.md loaded and parsed
 - [ ] All v1 requirements mapped to exactly one phase (100% coverage)
- [ ] `.planning/ROADMAP.md` exists with requirement mappings
+- [ ] **Success criteria derived** for each phase (2-5 observable behaviors)
+- [ ] **Success criteria cross-checked** against requirements (no gaps)
+- [ ] `.planning/ROADMAP.md` exists with requirement mappings and success criteria
 - [ ] `.planning/STATE.md` exists (project memory initialized)
 - [ ] REQUIREMENTS.md traceability section updated
 - [ ] Phases defined with clear names (count derived from requirements, not imposed)
--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -240,6 +240,120 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
 **If neither exist:** Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.
 </step>

+<step name="derive_must_haves">
+**BEFORE breaking into tasks, work BACKWARD from the phase goal.**
+
+This step prevents the common failure mode: tasks complete but goal not achieved.
+
+See `~/.claude/get-shit-done/references/goal-backward.md` for complete guidance.
+
+**1. State the phase goal:**
+
+Extract from ROADMAP.md. Reframe if task-shaped:
+- Task-shaped: "implement chat system" → Outcome-shaped: "users can chat"
+- Task-shaped: "add authentication" → Outcome-shaped: "users can log in securely"
+
+**2. Derive observable truths:**
+
+Ask: **"What must be TRUE for this goal to be achieved?"**
+
+List 3-7 truths from the USER's perspective:
+- "User can see existing messages"
+- "User can type and send a message"
+- "Sent message appears in the list"
+- "Messages persist across refresh"
+
+**Test:** Each truth should be verifiable by a human using the app. If you can't test it by clicking around, it's not observable.
+
+**3. Derive required artifacts:**
+
+For each truth, ask: **"What must EXIST for this to be true?"**
+
+Map truths to concrete files:
+```
+"User can see existing messages" requires:
+  - src/components/Chat.tsx (renders messages)
+  - src/app/api/chat/route.ts (provides messages)
+  - prisma/schema.prisma (Message model)
+```
+
+**Test:** Each artifact should be a specific file path. If you can't point to where it lives, it's too abstract.
+
+**4. Derive key links (wiring):**
+
+For each artifact, ask: **"What must be CONNECTED for this to function?"**
+
+Key links are critical connections:
+```
+- Chat.tsx → /api/chat: fetch in useEffect, response mapped to state
+- /api/chat GET → database: prisma.message.findMany, result returned
+- ChatInput onSubmit → /api/chat POST: fetch call, not just console.log
+```
+
+**Test:** Wiring is verified by tracing data flow. Does A actually call B?
+
+**5. Identify highest-risk links:**
+
+Ask: **"Where is this most likely to break?"**
+
+These get extra verification attention. Common high-risk links:
+- Form submit → API call (often stubbed with console.log)
+- API handler → database query (often returns hardcoded data)
+- Component → real data (often renders placeholder)
+
+**6. Document must-haves:**
+
+Structure for PLAN.md frontmatter:
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+    - "Messages persist across refresh"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 30
+    - path: "src/app/api/chat/route.ts"
+      provides: "Message CRUD"
+      exports: ["GET", "POST"]
+    - path: "prisma/schema.prisma"
+      provides: "Message model"
+      contains: "model Message"
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+      pattern: "fetch.*api/chat"
+    - from: "src/app/api/chat/route.ts"
+      to: "prisma.message"
+      via: "database query"
+      pattern: "prisma\\.message"
+```
+
+**7. Use must-haves to inform task design:**
+
+Tasks should CREATE artifacts and ESTABLISH key links. When writing tasks:
+- Each artifact should have a task that creates it
+- Each key link should be established (not left as TODO)
+- Verification should check the link works, not just that files exist
+
+**Why this matters:**
+
+Without goal-backward derivation, you get:
+- "Create Chat.tsx" ✓ (file exists, but renders placeholder)
+- "Create API route" ✓ (file exists, but returns hardcoded data)
+- "Phase complete" ✓ (all tasks done)
+- "App doesn't work" ✗ (goal not achieved)
+
+With goal-backward derivation:
+- Must-haves define what "working" means
+- Tasks are designed to achieve must-haves
+- Verification checks must-haves after execution
+- Gaps found before they compound into later phases
+</step>
+
 <step name="break_into_tasks">
 Decompose phase into tasks. **Think dependencies first, not sequence.**

@@ -733,14 +847,17 @@ Phase planning complete when:
 - [ ] STATE.md read, project history absorbed
 - [ ] Mandatory discovery completed (Level 0-3)
 - [ ] Prior decisions, issues, concerns synthesized
+- [ ] **Must-haves derived** (truths, artifacts, key links from goal-backward analysis)
 - [ ] Dependency graph built (needs/creates for each task)
 - [ ] Tasks grouped into plans by wave, not by sequence
 - [ ] PLAN file(s) exist with XML structure
 - [ ] Each plan: depends_on, files_modified, autonomous in frontmatter
+- [ ] **Each plan: must_haves in frontmatter** (for post-execution verification)
 - [ ] Each plan: user_setup declared if external services involved
 - [ ] Each plan: Objective, context, tasks, verification, success criteria, output
 - [ ] Each plan: 2-3 tasks (~50% context)
 - [ ] Each task: Type, Files (if auto), Action, Verify, Done
+- [ ] **Tasks designed to CREATE artifacts and ESTABLISH key links**
 - [ ] Checkpoints properly structured
 - [ ] Wave structure maximizes parallelism
 - [ ] PLAN file(s) committed to git