From 3fddd62d50ed8ec7abf15474cae924319be2c282 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 23 Feb 2026 14:00:42 -0600 Subject: [PATCH] =?UTF-8?q?feat:=20planning=20improvements=20=E2=80=94=20P?= =?UTF-8?q?RD=20express=20path,=20interface-first=20planning,=20living=20r?= =?UTF-8?q?etrospective=20(#644)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cherry-pick from @smledbetter with conflict resolution and project-specific reference removed. Co-Authored-By: Stevo Co-Authored-By: Claude Opus 4.6 --- agents/gsd-planner.md | 83 ++++++++++++++++ commands/gsd/plan-phase.md | 3 +- get-shit-done/templates/retrospective.md | 54 +++++++++++ get-shit-done/workflows/complete-milestone.md | 63 +++++++++++++ get-shit-done/workflows/discuss-phase.md | 2 + get-shit-done/workflows/execute-plan.md | 2 + get-shit-done/workflows/help.md | 3 + get-shit-done/workflows/plan-phase.md | 94 ++++++++++++++++++- 8 files changed, 302 insertions(+), 2 deletions(-) create mode 100644 get-shit-done/templates/retrospective.md diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index b576531f6..ffa1723f8 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -200,6 +200,16 @@ Each task: **15-60 minutes** Claude execution time. **Combine signals:** One task sets up for the next, separate tasks touch same file, neither meaningful alone. +## Interface-First Task Ordering + +When a plan creates new interfaces consumed by subsequent tasks: + +1. **First task: Define contracts** — Create type files, interfaces, exports +2. **Middle tasks: Implement** — Build against the defined contracts +3. **Last task: Wire** — Connect implementations to consumers + +This prevents the "scavenger hunt" anti-pattern where executors explore the codebase to understand contracts. They receive the contracts in the plan itself. + ## Specificity Examples | TOO VAGUE | JUST RIGHT | @@ -445,6 +455,69 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` Wave numbers are pre-computed during planning. Execute-phase reads `wave` directly from frontmatter. +## Interface Context for Executors + +**Key insight:** "The difference between handing a contractor blueprints versus telling them 'build me a house.'" + +When creating plans that depend on existing code or create new interfaces consumed by other plans: + +### For plans that USE existing code: +After determining `files_modified`, extract the key interfaces/types/exports from the codebase that executors will need: + +```bash +# Extract type definitions, interfaces, and exports from relevant files +grep -n "export\|interface\|type\|class\|function" {relevant_source_files} 2>/dev/null | head -50 +``` + +Embed these in the plan's `` section as an `` block: + +```xml + + + + +From src/types/user.ts: +```typescript +export interface User { + id: string; + email: string; + name: string; + createdAt: Date; +} +``` + +From src/api/auth.ts: +```typescript +export function validateToken(token: string): Promise; +export function createSession(user: User): Promise; +``` + +``` + +### For plans that CREATE new interfaces: +If this plan creates types/interfaces that later plans depend on, include a "Wave 0" skeleton step: + +```xml + + Task 0: Write interface contracts + src/types/newFeature.ts + Create type definitions that downstream plans will implement against. These are the contracts — implementation comes in later tasks. + File exists with exported types, no implementation + Interface file committed, types exported + +``` + +### When to include interfaces: +- Plan touches files that import from other modules → extract those module's exports +- Plan creates a new API endpoint → extract the request/response types +- Plan modifies a component → extract its props interface +- Plan depends on a previous plan's output → extract the types from that plan's files_modified + +### When to skip: +- Plan is self-contained (creates everything from scratch, no imports) +- Plan is pure configuration (no code interfaces involved) +- Level 0 discovery (all patterns already established) + ## Context Section Rules Only include prior plan SUMMARY references if genuinely needed (uses types/exports from prior plan, or prior plan made decision affecting this one). @@ -954,6 +1027,16 @@ For phases not selected, retain from digest: - `patterns`: Conventions to follow **From STATE.md:** Decisions → constrain approach. Pending todos → candidates. + +**From RETROSPECTIVE.md (if exists):** +```bash +cat .planning/RETROSPECTIVE.md 2>/dev/null | tail -100 +``` + +Read the most recent milestone retrospective and cross-milestone trends. Extract: +- **Patterns to follow** from "What Worked" and "Patterns Established" +- **Patterns to avoid** from "What Was Inefficient" and "Key Lessons" +- **Cost patterns** to inform model selection and agent strategy diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 5f92e86c8..bb377a897 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -1,7 +1,7 @@ --- name: gsd:plan-phase description: Create detailed phase plan (PLAN.md) with verification loop -argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify]" +argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd ]" agent: gsd-planner allowed-tools: - Read @@ -34,6 +34,7 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit - `--skip-research` — Skip research, go straight to planning - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research) - `--skip-verify` — Skip verification loop +- `--prd ` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely. Normalize phase input in step 2 before any directory lookups. diff --git a/get-shit-done/templates/retrospective.md b/get-shit-done/templates/retrospective.md new file mode 100644 index 000000000..e804ca976 --- /dev/null +++ b/get-shit-done/templates/retrospective.md @@ -0,0 +1,54 @@ +# Project Retrospective + +*A living document updated after each milestone. Lessons feed forward into future planning.* + +## Milestone: v{version} — {name} + +**Shipped:** {date} +**Phases:** {count} | **Plans:** {count} | **Sessions:** {count} + +### What Was Built +- {Key deliverable 1} +- {Key deliverable 2} +- {Key deliverable 3} + +### What Worked +- {Efficiency win or successful pattern} +- {What went smoothly} + +### What Was Inefficient +- {Missed opportunity} +- {What took longer than expected} + +### Patterns Established +- {New pattern or convention that should persist} + +### Key Lessons +1. {Specific, actionable lesson} +2. {Another lesson} + +### Cost Observations +- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku +- Sessions: {count} +- Notable: {efficiency observation} + +--- + +## Cross-Milestone Trends + +### Process Evolution + +| Milestone | Sessions | Phases | Key Change | +|-----------|----------|--------|------------| +| v{X} | {N} | {M} | {What changed in process} | + +### Cumulative Quality + +| Milestone | Tests | Coverage | Zero-Dep Additions | +|-----------|-------|----------|-------------------| +| v{X} | {N} | {Y}% | {count} | + +### Top Lessons (Verified Across Milestones) + +1. {Lesson verified by multiple milestones} +2. {Another cross-validated lesson} diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md index 3dace3c6f..63bcf6519 100644 --- a/get-shit-done/workflows/complete-milestone.md +++ b/get-shit-done/workflows/complete-milestone.md @@ -438,6 +438,67 @@ rm .planning/REQUIREMENTS.md + + +**Append to living retrospective:** + +Check for existing retrospective: +```bash +ls .planning/RETROSPECTIVE.md 2>/dev/null +``` + +**If exists:** Read the file, append new milestone section before the "## Cross-Milestone Trends" section. + +**If doesn't exist:** Create from template at `~/.claude/get-shit-done/templates/retrospective.md`. + +**Gather retrospective data:** + +1. From SUMMARY.md files: Extract key deliverables, one-liners, tech decisions +2. From VERIFICATION.md files: Extract verification scores, gaps found +3. From UAT.md files: Extract test results, issues found +4. From git log: Count commits, calculate timeline +5. From the milestone work: Reflect on what worked and what didn't + +**Write the milestone section:** + +```markdown +## Milestone: v{version} — {name} + +**Shipped:** {date} +**Phases:** {phase_count} | **Plans:** {plan_count} + +### What Was Built +{Extract from SUMMARY.md one-liners} + +### What Worked +{Patterns that led to smooth execution} + +### What Was Inefficient +{Missed opportunities, rework, bottlenecks} + +### Patterns Established +{New conventions discovered during this milestone} + +### Key Lessons +{Specific, actionable takeaways} + +### Cost Observations +- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku +- Sessions: {count} +- Notable: {efficiency observation} +``` + +**Update cross-milestone trends:** + +If the "## Cross-Milestone Trends" section exists, update the tables with new data from this milestone. + +**Commit:** +```bash +node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md +``` + + + Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields: @@ -695,6 +756,8 @@ Milestone completion is successful when: - [ ] Requirements completion checked against REQUIREMENTS.md traceability table - [ ] Incomplete requirements surfaced with proceed/audit/abort options - [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements +- [ ] RETROSPECTIVE.md updated with milestone section +- [ ] Cross-milestone trends updated - [ ] User knows next step (/gsd:new-milestone) diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index 6155b216a..1b9596dac 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -107,6 +107,8 @@ Phase: "API documentation" +**Express path available:** If you already have a PRD or acceptance criteria document, use `/gsd:plan-phase {phase} --prd path/to/prd.md` to skip this discussion and go straight to planning. + Phase number from argument (required). diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index fc6c61c37..a838b0c73 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -118,6 +118,8 @@ Pattern B only (verify-only checkpoints). Skip for A/C. cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md ``` This IS the execution instructions. Follow exactly. If plan references CONTEXT.md: honor user's vision throughout. + +**If plan contains `` block:** These are pre-extracted type definitions and contracts. Use them directly — do NOT re-read the source files to discover types. The planner already extracted what you need. diff --git a/get-shit-done/workflows/help.md b/get-shit-done/workflows/help.md index b327f5803..2991aa18e 100644 --- a/get-shit-done/workflows/help.md +++ b/get-shit-done/workflows/help.md @@ -99,6 +99,8 @@ Create detailed execution plan for a specific phase. Usage: `/gsd:plan-phase 1` Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md` +**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria. + ### Execution **`/gsd:execute-phase `** @@ -351,6 +353,7 @@ Usage: `/gsd:join-discord` ├── PROJECT.md # Project vision ├── ROADMAP.md # Current phase breakdown ├── STATE.md # Project memory & context +├── RETROSPECTIVE.md # Living retrospective (updated per milestone) ├── config.json # Workflow mode & gates ├── todos/ # Captured ideas and tasks │ ├── pending/ # Todos waiting to be worked on diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index f292e79e9..91a788719 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -26,7 +26,9 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_ ## 2. Parse and Normalize Arguments -Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`). +Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--prd `). + +Extract `--prd ` from $ARGUMENTS. If present, set PRD_FILE to the filepath. **If no phase number:** Detect next unplanned phase from roadmap. @@ -45,8 +47,98 @@ PHASE_INFO=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$ **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON. +## 3.5. Handle PRD Express Path + +**Skip if:** No `--prd` flag in arguments. + +**If `--prd ` provided:** + +1. Read the PRD file: +```bash +PRD_CONTENT=$(cat "$PRD_FILE" 2>/dev/null) +if [ -z "$PRD_CONTENT" ]; then + echo "Error: PRD file not found: $PRD_FILE" + exit 1 +fi +``` + +2. Display banner: +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► PRD EXPRESS PATH +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +Using PRD: {PRD_FILE} +Generating CONTEXT.md from requirements... +``` + +3. Parse the PRD content and generate CONTEXT.md. The orchestrator should: + - Extract all requirements, user stories, acceptance criteria, and constraints from the PRD + - Map each to a locked decision (everything in the PRD is treated as a locked decision) + - Identify any areas the PRD doesn't cover and mark as "Claude's Discretion" + - Create CONTEXT.md in the phase directory + +4. Write CONTEXT.md: +```markdown +# Phase [X]: [Name] - Context + +**Gathered:** [date] +**Status:** Ready for planning +**Source:** PRD Express Path ({PRD_FILE}) + + +## Phase Boundary + +[Extracted from PRD — what this phase delivers] + + + + +## Implementation Decisions + +{For each requirement/story/criterion in the PRD:} +### [Category derived from content] +- [Requirement as locked decision] + +### Claude's Discretion +[Areas not covered by PRD — implementation details, technical choices] + + + + +## Specific Ideas + +[Any specific references, examples, or concrete requirements from PRD] + + + + +## Deferred Ideas + +[Items in PRD explicitly marked as future/v2/out-of-scope] +[If none: "None — PRD covers phase scope"] + + + +--- + +*Phase: XX-name* +*Context gathered: [date] via PRD Express Path* +``` + +5. Commit: +```bash +node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md" +``` + +6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research). + +**Effect:** This completely bypasses step 4 (Load CONTEXT.md) since we just created it. The rest of the workflow (research, planning, verification) proceeds normally with the PRD-derived context. + ## 4. Load CONTEXT.md +**Skip if:** PRD express path was used (CONTEXT.md already created in step 3.5). + Check `context_path` from init JSON. If `context_path` is not null, display: `Using phase context from: ${context_path}`