msd-core/optimisation-ideas/ACTION-PLAN.md

GSD Context Optimization: Action Plan

Consensus Across All Syntheses

All three proposals agree on the first two phases. Divergence begins at Phase 3 (how far to push deterministic orchestration). This plan executes the consensus first, then evaluates before committing to architectural changes.

---

Phase 1: Quick Wins (Do First)

Why first: Highest ROI, lowest risk, validates the approach before bigger changes.

1.1 History Digest

What: Add gsd-tools history-digest command that extracts frontmatter from SUMMARY.md files into a structured JSON.

Why: 10 summaries = 500-1000 lines → 2KB JSON. 80-90% reduction in history context.

Implementation:

// bin/gsd-tools.js
case 'history-digest':
  const summaries = glob.sync('.planning/phases/*/*-SUMMARY.md');
  const digest = { phases: {}, decisions: [], tech_stack: new Set() };

  for (const file of summaries) {
    const frontmatter = extractFrontmatter(file);
    // Extract: provides, patterns, affects, decisions, tech-stack
  }

  console.log(JSON.stringify(digest, null, 2));

Acceptance: Planner uses digest instead of reading full summaries.

---

1.2 Atomic State Operations

What: Add gsd-tools state get <section> and gsd-tools state patch --key value.

Why: Agents currently hold full STATE.md (50-100 lines) throughout execution. Patch operations read/write only what's needed.

Implementation:

case 'state':
  if (args[1] === 'get') {
    // Return specific section as JSON
  }
  if (args[1] === 'patch') {
    // Parse flags, apply atomic updates
  }

Acceptance: Executor uses state patch instead of rewriting full file.

---

1.3 Summary Template Variants

What: Create three templates: summary-minimal.md (~30 lines), summary-standard.md (~60 lines), summary-complex.md (~100 lines).

Why: A 2-task config change doesn't need a 114-line summary template.

Selection logic:

• Minimal: ≤2 tasks, ≤3 files, no decisions
• Complex: Has decisions OR >6 files
• Standard: Everything else

Acceptance: Executor selects template based on plan metadata.

---

1.4 Finish Compound Init Sweep

What: Ensure all major workflows use compound init calls.

Why: Already proven in v1.12.x. Consolidates 5-10 atomic calls into single payload.

Targets: new-project.md, complete-milestone.md, verify-work.md, transition.md, help.md, discuss-phase.md

---

Phase 2: Tiered Agent Architecture (Do Second)

Why second: Addresses the biggest context hogs (planner: 55KB, executor: 19KB) but requires more careful refactoring.

2.1 Split Executor

What: Extract protocols into separate reference files, load conditionally.

Before:

agents/gsd-executor.md (382 lines, ~19KB)
  - deviation_rules (60 lines) - always loaded
  - checkpoint_protocol (40 lines) - always loaded
  - tdd_execution (30 lines) - always loaded
  - continuation_handling (20 lines) - always loaded

After:

agents/gsd-executor-core.md (~150 lines)

references/executor/
  deviation-rules.md      # Always loaded (core identity)
  tdd-execution.md        # Loaded if task.tdd="true"
  checkpoint-protocol.md  # Loaded if task.type="checkpoint:*"
  continuation.md         # Loaded if <completed_tasks> present

Loading logic: Executor uses @ references conditionally based on task metadata.

Acceptance: Executor base context drops from ~19KB to ~8KB.

---

2.2 Split Planner

What: Extract mode-specific logic into extensions.

Before:

agents/gsd-planner.md (1,116 lines, ~55KB)

After:

agents/gsd-planner-core.md (~300 lines)
  - role, philosophy, context_fidelity
  - task_breakdown (core)
  - plan_format
  - execution_flow (standard path)

agents/gsd-planner-ext/
  gap-closure.md    # Loaded if --gaps flag
  revision.md       # Loaded if checker issues
  tdd.md            # Loaded if TDD candidates detected
  checkpoints.md    # Loaded if phase has checkpoints

Orchestrator assembles prompt dynamically based on flags and phase characteristics.

Acceptance: Planner base context drops from ~55KB to ~20KB.

---

Phase 3: Compiled Plans (Do Third)

Why third: Depends on stable tiered agents. Provides incremental gains on top of Phase 2.

3.1 Implement compile-plan

What: Add gsd-tools compile-plan <path> that:

1. Inlines all @ references
2. Strips sections unused by this plan (no TDD tasks → remove TDD sections)
3. Outputs .compiled.md ready for execution

Why: Eliminates runtime @ resolution. Pre-strips unused protocols.

Staleness handling:

• Check mtime before execution
• .compiled.md in .gitignore
• Recompile on GSD update

Acceptance: Plans execute from compiled form, ~30-40% context reduction.

---

Phase 4: Evaluate Railroad (Decide Later)

Why later: High effort, architectural risk. Phases 1-3 may provide sufficient improvement.

The question: Should gsd-tools become a state machine that tells Claude "do this next" instead of Claude reading workflow files?

Arguments for:

• Maximum context reduction
• Deterministic execution (can't skip steps)
• LLM focuses purely on task, not process

Arguments against:

• Loses adaptive intelligence
• Can't handle mid-execution surprises
• Debugging split across code and prompts
• Near-total rewrite

Decision point: After Phase 3, measure context usage. If still >40% at task start, consider Railroad. If <40%, skip.

---

Phase 5: Semantic Queries (Optional)

Why optional: gsd-memory MCP exists. Only invest here if grep-based lookups prove insufficient after other optimizations.

What: Extend gsd-memory with structured queries:

gsd_memory_what_uses({ symbol: "User", type: "model" })
gsd_memory_pattern_for({ domain: "auth" })

Decision point: After Phase 3, evaluate if history/pattern lookups are still a bottleneck.

---

Execution Order Summary

IMMEDIATE (Phase 1) - 1-2 days
├── 1.1 history-digest command
├── 1.2 state get/patch commands
├── 1.3 Summary template variants
└── 1.4 Compound init sweep completion

NEXT (Phase 2) - 3-5 days
├── 2.1 Split gsd-executor into core + references
└── 2.2 Split gsd-planner into core + extensions

THEN (Phase 3) - 3-5 days
└── 3.1 compile-plan command

EVALUATE (Phase 4) - Decision point
└── Measure: Is context <40%?
    └── Yes → Done
    └── No → Consider Railroad architecture

OPTIONAL (Phase 5)
└── Semantic MCP queries (only if needed)

---

Success Metrics

Metric	Current	Phase 1	Phase 2	Phase 3	Target
Executor base	~19KB	~19KB	~8KB	~6KB	<8KB
Planner base	~55KB	~55KB	~20KB	~18KB	<20KB
History (10 phases)	~20KB	~2KB	~2KB	~2KB	<3KB
Task start context	~25%	~18%	~12%	~10%	<15%

---

What NOT To Do

1. Don't implement Railroad before Phase 3 measurement. The architectural cost is high; validate simpler solutions first.

2. Don't compress instructional content. The teaching content is GSD's value. Optimize when it loads, not what it says.

3. Don't over-engineer caching. Simple mtime checks work. No cache invalidation logic until proven necessary.

4. Don't parallelize phases. Each phase validates assumptions for the next. Sequential execution reduces risk.

---

Next Action

Start Phase 1.1: Implement gsd-tools history-digest.