From 87909f97ae42900aa414693cfc5d6a2024282ff5 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 09:34:48 -0600 Subject: [PATCH] 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 --- commands/gsd/create-roadmap.md | 5 +- commands/gsd/plan-phase.md | 2 + get-shit-done/templates/phase-prompt.md | 77 ++++++++++++++ get-shit-done/templates/roadmap.md | 23 +++++ get-shit-done/workflows/create-roadmap.md | 95 +++++++++++++++++- get-shit-done/workflows/plan-phase.md | 117 ++++++++++++++++++++++ 6 files changed, 317 insertions(+), 2 deletions(-) diff --git a/commands/gsd/create-roadmap.md b/commands/gsd/create-roadmap.md index 3b9421729..40ba4faea 100644 --- 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 @@ -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 diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 213d46ec8..1699abdc0 100644 --- 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 @@ -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) diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index af364da80..a87987908 100644 --- 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 --- @@ -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. diff --git a/get-shit-done/templates/roadmap.md b/get-shit-done/templates/roadmap.md index ae90932e0..8bef7b949 100644 --- 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 diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md index 56b1a5be6..a241ce3b2 100644 --- 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 + +**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 + + **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) diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index 4b7a2bd4b..a06020831 100644 --- 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. + +**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 + + 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