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>
This commit is contained in:
Lex Christopherson
2026-01-15 09:34:48 -06:00
parent 869f02e973
commit 87909f97ae
6 changed files with 317 additions and 2 deletions

View File

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

View File

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