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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-22 11:11:16 -06:00
parent 314916bae9
commit 7ba5dbd412
11 changed files with 18 additions and 170 deletions

View File

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

View File

@@ -201,21 +201,8 @@ Do NOT offer manual next steps - verify-work handles the rest.
</process>
<context_efficiency>
**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).
</context_efficiency>
<failure_handling>

View File

@@ -550,24 +550,9 @@ All {N} phases executed.
</process>
<context_efficiency>
**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.
</context_efficiency>
<failure_handling>

View File

@@ -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.
</step>
<step name="load_prompt">
@@ -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
</task_commit>
<step name="checkpoint_protocol">

View File

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

View File

@@ -7,10 +7,7 @@ Use this workflow when:
</trigger>
<purpose>
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.
</purpose>
<required_reading>
@@ -290,17 +287,12 @@ This handles cases where:
</reconstruction>
<quick_resume>
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.
</quick_resume>
<success_criteria>

View File

@@ -514,15 +514,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone {version}")
</process>
<implicit_tracking>
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.
</implicit_tracking>
<partial_completion>