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:
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user