Task Decomposition

Plan complex work. Track it. Learn from it. Get better at planning over time.

Plan Format

Store plans in plans/ (workspace-relative). Name: [slug].plan.md. Multiple concurrent plans supported.

# Plan: Deploy new API
Started: 2026-03-03 11:00
Status: in-progress
Revised: 1

## Tasks

- [x] 1. (S) Provision database — Postgres 16, endpoint saved to .env
- [ ] 2. (M) Build auth middleware (depends: 1)
- [ ] 3. (M) Build CRUD endpoints (depends: 1)
      ↳ parallel with 2
- [ ] 4. (L) Integration tests (depends: 2, 3)
- [ ] 5. (S) Deploy to staging (depends: 4) ⚠️ blocked: waiting on VPN access
      spawned: session-k9x2

## Retro
<!-- filled on completion -->

Notation

• Size: (S) <30min, (M) 30min-2h, (L) 2h+
• Dependencies: (depends: 1, 3) = must complete first
• Parallel: ↳ parallel with N = concurrent with task N
• Blocked: ⚠️ blocked: [reason]
• Delegated: spawned: [session-id]
• Done: - [x] with outcome after dash: — result summary

Planning

1. Read the FULL request before decomposing
2. Identify boundaries: different tools, contexts, or outputs = different tasks
3. Mark real dependencies only — parallel what CAN be parallel
4. Size each task (S/M/L) — makes progress reports honest
5. Action-oriented names: "Install X", "Configure Y", "Verify Z"
6. Check plans/ for similar past plans — reuse what worked, avoid what didn't

Execution

1. Work in dependency order, parallelize where noted
2. Update plan after each TASK completes (not each tool call)
3. Blocked? Mark it, work next unblocked task
4. Record outcomes — future you needs them

Revision

Plans change mid-flight. When they do:

• Insert: Add with next number, update downstream depends:
• Remove: Strikethrough, don't renumber (preserves refs)
• Reorder: Update depends: only
• Bump the Revised: counter

Don't follow a bad plan to completion.

Resume (After Restart)

When you find an existing plan:

1. Read it — check Status
2. Find first unchecked, unblocked task
3. Quick sanity check that prior tasks still hold
4. Continue — or revise first if context changed

Failure

• Task fails → note it, assess: can downstream tasks still run?
• Unrecoverable → Status: abandoned, explain why
• Always record what DID work — partial progress has value

Sub-agent Delegation

• One sub-agent per independent BRANCH, not per task
• Record session ID on the task line
• Don't poll in loops — check on events or when asked

Progress Report

When asked "status?" or "where are we?":

📋 Plan: Deploy new API
Progress: 3/7 tasks (1L + 2S remaining)
Current: Task 4 (L) — running integration tests
Blocked: Task 5 — waiting on VPN access
Revised: 1x

Size-aware > task-count. "1/5 done" is misleading when the 4 remaining are all (L).

Learning Loop ← what makes plans improve

Retro (on completion)

When a plan finishes (completed or abandoned), fill the ## Retro section:

## Retro
- **What worked:** Parallelizing tasks 2+3 saved ~1h
- **What didn't:** Underestimated task 4 (sized M, was actually L)
- **Sizing accuracy:** 3/5 tasks sized correctly
- **Dependencies missed:** Task 5 actually needed task 2 directly, not just via 4
- **Reusable pattern:** [If this plan type recurs, note the template]

Patterns File

Maintain plans/patterns.md — distilled lessons from retros:

# Planning Patterns (learned from retros)

## Sizing
- API integration tasks: usually (M), not (S)
- "Write tests" is always bigger than you think → size up one level
- Database migrations with data backfill: always (L)

## Dependencies
- Auth must come before any authenticated endpoint work
- Don't parallelize tasks that write to the same config file

## Templates
- **API build:** provision → auth + endpoints (parallel) → tests → deploy
- **Research report:** gather sources → analyze (parallel per source) → synthesize → review

This file gets checked during Step 6 of Planning ("check past plans"). Over time, sizing gets more accurate, dependency mistakes stop repeating, and common project types get reusable templates.

Decay

Review patterns.md monthly. Remove patterns that:

• Haven't applied in 30+ days
• Were wrong more than once
• Are too project-specific to generalize

Archive

Completed/abandoned plans → rename [date]-[slug].plan.md:

plans/
├── deploy-api.plan.md              # active
├── patterns.md                     # learned patterns
├── 2026-03-01-setup-acw.plan.md    # archived
└── 2026-03-02-osint-recon.plan.md  # archived

Anti-patterns

• Over-decomposition: 15 tasks for 4 steps of real work
• Phantom dependencies: Marking sequential what's actually parallel
• Plan worship: Following a wrong plan because it exists
• Size blindness: "4/5 done!" when the remaining task is (L)
• Skipping retros: No retro = no learning = same mistakes forever