From 7ba5dbd412db85d856def8b335c5a5c970325aa0 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 22 Jan 2026 11:11:16 -0600 Subject: [PATCH] refactor: condense verbose explanations in templates and workflows Trim redundant documentation while preserving actionable instructions. -173 lines of prose that restated what templates already show. Kept: size constraints, mandatory fields, security guidance. Removed: "when to create/read/update" lifecycle prose, section descriptions that duplicate template structure. Co-Authored-By: Claude Opus 4.5 --- get-shit-done/templates/context.md | 8 ----- get-shit-done/templates/state.md | 30 ---------------- get-shit-done/templates/summary.md | 31 +++-------------- get-shit-done/templates/user-setup.md | 14 +------- get-shit-done/workflows/complete-milestone.md | 7 +--- get-shit-done/workflows/diagnose-issues.md | 17 ++-------- get-shit-done/workflows/execute-phase.md | 21 ++---------- get-shit-done/workflows/execute-plan.md | 34 ++----------------- .../workflows/list-phase-assumptions.md | 4 +-- get-shit-done/workflows/resume-project.md | 12 ++----- get-shit-done/workflows/transition.md | 10 +----- 11 files changed, 18 insertions(+), 170 deletions(-) diff --git a/get-shit-done/templates/context.md b/get-shit-done/templates/context.md index 681eac564..cdfffa531 100644 --- a/get-shit-done/templates/context.md +++ b/get-shit-done/templates/context.md @@ -275,14 +275,6 @@ The output should answer: "What does the researcher need to investigate? What ch - "Fast and responsive" - "Easy to use" -**Sections explained:** - -- **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary. -- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc. -- **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation. -- **Specifics** — Product references, examples, "like X but..." statements. -- **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas. - **After creation:** - File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md` - `gsd-phase-researcher` uses decisions to focus investigation diff --git a/get-shit-done/templates/state.md b/get-shit-done/templates/state.md index 159ae00cc..3e5b50304 100644 --- a/get-shit-done/templates/state.md +++ b/get-shit-done/templates/state.md @@ -174,33 +174,3 @@ It's a DIGEST, not an archive. If accumulated context grows too large: The goal is "read once, know where we are" — if it's too long, that fails. - - - -**When created:** -- During project initialization (after ROADMAP.md) -- Reference PROJECT.md (extract core value and current focus) -- Initialize empty sections - -**When read:** -- Every workflow starts by reading STATE.md -- Then read PROJECT.md for full context -- Provides instant context restoration - -**When updated:** -- After each plan execution (update position, note decisions, update issues/blockers) -- After phase transitions (update progress bar, clear resolved blockers, refresh project reference) - -**Size management:** -- Keep under 100 lines total -- Recent decisions only in STATE.md (full log in PROJECT.md) -- Keep only active blockers - -**Sections:** -- Project Reference: Pointer to PROJECT.md with core value -- Current Position: Where we are now (phase, plan, status) -- Performance Metrics: Velocity tracking -- Accumulated Context: Recent decisions, pending todos, blockers -- Session Continuity: Resume information - - diff --git a/get-shit-done/templates/summary.md b/get-shit-done/templates/summary.md index 3c699b100..26c425217 100644 --- a/get-shit-done/templates/summary.md +++ b/get-shit-done/templates/summary.md @@ -233,37 +233,14 @@ The one-liner should tell someone what actually shipped. -**When to create:** -- After completing each phase plan -- Required output from execute-plan workflow -- Documents what actually happened vs what was planned +**Frontmatter:** MANDATORY - complete all fields. Enables automatic context assembly for future planning. -**Frontmatter completion:** -- MANDATORY: Complete all frontmatter fields during summary creation -- See for field purposes -- Frontmatter enables automatic context assembly for future planning - -**One-liner requirements:** -- Must be substantive (describe what shipped, not "phase complete") -- Should tell someone what was accomplished -- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented" - -**Performance tracking:** -- Include duration, start/end timestamps -- Used for velocity metrics in STATE.md - -**Deviations section:** -- Documents unplanned work handled via deviation rules -- Separate from "Issues Encountered" (which is planned work problems) -- Auto-fixed issues: What was wrong, how fixed, verification +**One-liner:** Must be substantive. "JWT auth with refresh rotation using jose library" not "Authentication implemented". **Decisions section:** -- Key decisions made during execution -- Include rationale (why this choice) +- Key decisions made during execution with rationale - Extracted to STATE.md accumulated context - Use "None - followed plan as specified" if no deviations -**After creation:** -- STATE.md updated with position, decisions, issues -- Next plan can reference decisions made +**After creation:** STATE.md updated with position, decisions, issues. diff --git a/get-shit-done/templates/user-setup.md b/get-shit-done/templates/user-setup.md index 8d0475909..260a8552b 100644 --- a/get-shit-done/templates/user-setup.md +++ b/get-shit-done/templates/user-setup.md @@ -304,20 +304,8 @@ curl -X POST http://localhost:3000/api/test-email \ ## Guidelines -**Include in USER-SETUP.md:** -- Environment variable names and where to find values -- Account creation URLs (if new service) -- Dashboard configuration steps -- Verification commands to confirm setup works -- Local development alternatives (e.g., `stripe listen`) - -**Do NOT include:** -- Actual secret values (never) -- Steps Claude can automate (package installs, code changes, file creation) -- Generic instructions ("set up your environment") +**Never include:** Actual secret values. Steps Claude can automate (package installs, code changes). **Naming:** `{phase}-USER-SETUP.md` matches the phase number pattern. - **Status tracking:** User marks checkboxes and updates status line when complete. - **Searchability:** `grep -r "USER-SETUP" .planning/` finds all phases with user requirements. diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md index cd90a2fb6..6a4d38ead 100644 --- a/get-shit-done/workflows/complete-milestone.md +++ b/get-shit-done/workflows/complete-milestone.md @@ -29,12 +29,7 @@ When a milestone completes, this workflow: 5. Performs full PROJECT.md evolution review 6. Offers to create next milestone inline -**Context Efficiency:** - -- Completed milestones: One line each (~50 tokens) -- Full details: In archive files (loaded only when needed) -- Result: ROADMAP.md stays constant size forever -- Result: REQUIREMENTS.md is always milestone-scoped (not cumulative) +**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped. **Archive Format:** diff --git a/get-shit-done/workflows/diagnose-issues.md b/get-shit-done/workflows/diagnose-issues.md index ce28df4ab..a463a15b0 100644 --- a/get-shit-done/workflows/diagnose-issues.md +++ b/get-shit-done/workflows/diagnose-issues.md @@ -201,21 +201,8 @@ Do NOT offer manual next steps - verify-work handles the rest. -**Orchestrator context:** ~15% -- Parse UAT.md gaps -- Fill template strings -- Spawn parallel Task calls -- Collect results -- Update UAT.md - -**Each debug agent:** Fresh 200k context -- Loads full debug workflow -- Loads debugging references -- Investigates with full capacity -- Returns root cause - -**No symptom gathering.** Agents start with symptoms pre-filled from UAT. -**No fix application.** Agents only diagnose - plan-phase --gaps handles fixes. +Agents start with symptoms pre-filled from UAT (no symptom gathering). +Agents only diagnose—plan-phase --gaps handles fixes (no fix application). diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 93f3a327b..13aea74ba 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -550,24 +550,9 @@ All {N} phases executed. -**Why this works:** - -Orchestrator context usage: ~10-15% -- Read plan frontmatter (small) -- Analyze dependencies (logic, no heavy reads) -- Fill template strings -- Spawn Task calls -- Collect results - -Each subagent: Fresh 200k context -- Loads full execute-plan workflow -- Loads templates, references -- Executes plan with full capacity -- Creates SUMMARY, commits - -**No polling.** Task tool blocks until completion. No TaskOutput loops. - -**No context bleed.** Orchestrator never reads workflow internals. Just paths and results. +Orchestrator: ~10-15% context (frontmatter, spawning, results). +Subagents: Fresh 200k each (full workflow + execution). +No polling (Task blocks). No context bleed. diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index d21c978f1..c671ace00 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -216,19 +216,7 @@ Tasks 2-5: Main context (need decision from checkpoint 1) No segmentation benefit - execute entirely in main ``` -**4. Why this works:** - -**Segmentation benefits:** - -- Fresh context for each autonomous segment (0% start every time) -- Main context only for checkpoints (~10-20% total) -- Can handle 10+ task plans if properly segmented -- Quality impossible to degrade in autonomous segments - -**When segmentation provides no benefit:** - -- Checkpoint is decision/human-action and following tasks depend on outcome -- Better to execute sequentially in main than break flow +**4. Why segment:** Fresh context per subagent preserves peak quality. Main context stays lean (~15% usage). **5. Implementation:** @@ -533,18 +521,7 @@ Committing... ```` -**Benefits of this pattern:** -- Main context usage: ~20% (just orchestration + checkpoints) -- Subagent 1: Fresh 0-30% (tasks 1-3) -- Subagent 2: Fresh 0-30% (tasks 5-6) -- Subagent 3: Fresh 0-20% (task 8) -- All autonomous work: Peak quality -- Can handle large plans with many tasks if properly segmented - -**When NOT to use segmentation:** -- Plan has decision/human-action checkpoints that affect following tasks -- Following tasks depend on checkpoint outcome -- Better to execute in main sequentially in those cases +**Benefit:** Each subagent starts fresh (~20-30% context), enabling larger plans without quality degradation. @@ -1068,13 +1045,6 @@ Store in array or list for SUMMARY generation: TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}") ``` -**Atomic commit benefits:** -- Each task independently revertable -- Git bisect finds exact failing task -- Git blame traces line to specific task context -- Clear history for Claude in future sessions -- Better observability for AI-automated workflow - diff --git a/get-shit-done/workflows/list-phase-assumptions.md b/get-shit-done/workflows/list-phase-assumptions.md index ac5fdbe5c..3269d2830 100644 --- a/get-shit-done/workflows/list-phase-assumptions.md +++ b/get-shit-done/workflows/list-phase-assumptions.md @@ -132,7 +132,7 @@ Wait for user response. Acknowledge the corrections: ``` -Got it. Key corrections: +Key corrections: - [correction 1] - [correction 2] @@ -142,7 +142,7 @@ This changes my understanding significantly. [Summarize new understanding] **If user confirms assumptions:** ``` -Great, assumptions validated. +Assumptions validated. ``` Continue to offer_next. diff --git a/get-shit-done/workflows/resume-project.md b/get-shit-done/workflows/resume-project.md index 30945075e..6047162a6 100644 --- a/get-shit-done/workflows/resume-project.md +++ b/get-shit-done/workflows/resume-project.md @@ -7,10 +7,7 @@ Use this workflow when: -Instantly restore full project context and present clear status. -Enables seamless session continuity for fully autonomous workflows. - -"Where were we?" should have an immediate, complete answer. +Instantly restore full project context so "Where were we?" has an immediate, complete answer. @@ -290,17 +287,12 @@ This handles cases where: -For users who want minimal friction: - -If user says just "continue" or "go": - +If user says "continue" or "go": - Load state silently - Determine primary action - Execute immediately without presenting options "Continuing from [state]... [action]" - -This enables fully autonomous "just keep going" workflow. diff --git a/get-shit-done/workflows/transition.md b/get-shit-done/workflows/transition.md index da99b6094..383a34c2a 100644 --- a/get-shit-done/workflows/transition.md +++ b/get-shit-done/workflows/transition.md @@ -514,15 +514,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone {version}") - -Progress tracking is IMPLICIT: - -- "Plan phase 2" → Phase 1 must be done (or ask) -- "Plan phase 3" → Phases 1-2 must be done (or ask) -- Transition workflow makes it explicit in ROADMAP.md - -No separate "update progress" step. Forward motion IS progress. - +Progress tracking is IMPLICIT: planning phase N implies phases 1-(N-1) complete. No separate progress step—forward motion IS progress.