todowrite-orchestration

What this skill does

# TodoWrite Orchestration

**Version:** 1.0.0
**Purpose:** Patterns for using TodoWrite in complex multi-phase workflows
**Status:** Production Ready

## Overview

TodoWrite orchestration is the practice of using the TodoWrite tool to provide **real-time progress visibility** in complex multi-phase workflows. It transforms opaque "black box" workflows into transparent, trackable processes where users can see:

- What phase is currently executing
- How many phases remain
- Which tasks are pending, in-progress, or completed
- Overall progress percentage
- Iteration counts in loops

This skill provides battle-tested patterns for:
- **Phase initialization** (create complete task list before starting)
- **Task granularity** (how to break phases into trackable tasks)
- **Status transitions** (pending → in_progress → completed)
- **Real-time updates** (mark complete immediately, not batched)
- **Iteration tracking** (progress through loops)
- **Parallel task tracking** (multiple agents executing simultaneously)

TodoWrite orchestration is especially valuable for workflows with >5 phases or >10 minutes duration, where users need progress feedback.

## Core Patterns

### Pattern 1: Phase Initialization

**Create TodoWrite List BEFORE Starting:**

Initialize TodoWrite as **step 0** of your workflow, before any actual work begins:

```
✅ CORRECT - Initialize First:

Step 0: Initialize TodoWrite
  TodoWrite: Create task list
    - PHASE 1: Gather user inputs
    - PHASE 1: Validate inputs
    - PHASE 2: Select AI models
    - PHASE 2: Estimate costs
    - PHASE 2: Get user approval
    - PHASE 3: Launch parallel reviews
    - PHASE 3: Wait for all reviews
    - PHASE 4: Consolidate reviews
    - PHASE 5: Present results

Step 1: Start actual work (PHASE 1)
  Mark "PHASE 1: Gather user inputs" as in_progress
  ... do work ...
  Mark "PHASE 1: Gather user inputs" as completed
  Mark "PHASE 1: Validate inputs" as in_progress
  ... do work ...

❌ WRONG - Create During Workflow:

Step 1: Do some work
  ... work happens ...
  TodoWrite: Create task "Did some work" (completed)

Step 2: Do more work
  ... work happens ...
  TodoWrite: Create task "Did more work" (completed)

Problem: User has no visibility into upcoming phases
```

**List All Phases Upfront:**

When initializing, include **all phases** in the task list, not just the current phase:

```
✅ CORRECT - Complete Visibility:

TodoWrite Initial State:
  [ ] PHASE 1: Gather user inputs
  [ ] PHASE 1: Validate inputs
  [ ] PHASE 2: Architecture planning
  [ ] PHASE 3: Implementation
  [ ] PHASE 3: Run quality checks
  [ ] PHASE 4: Code review
  [ ] PHASE 5: User acceptance
  [ ] PHASE 6: Generate report

User sees: "8 tasks total, 0 complete, Phase 1 starting"

❌ WRONG - Incremental Discovery:

TodoWrite Initial State:
  [ ] PHASE 1: Gather user inputs
  [ ] PHASE 1: Validate inputs

(User thinks workflow is 2 tasks, then surprised by 6 more phases)
```

**Why Initialize First:**

1. **User expectation setting:** User knows workflow scope (8 phases, ~20 minutes)
2. **Progress visibility:** User can see % complete (3/8 = 37.5%)
3. **Time estimation:** User can estimate remaining time based on progress
4. **Transparency:** No hidden phases or surprises

---

### Pattern 2: Task Granularity Guidelines

**One Task Per Significant Operation:**

Each task should represent a **significant operation** (1-5 minutes of work):

```
✅ CORRECT - Significant Operations:

Tasks:
  - PHASE 1: Ask user for inputs (30s)
  - PHASE 2: Generate architecture plan (2 min)
  - PHASE 3: Implement feature (5 min)
  - PHASE 4: Run tests (1 min)
  - PHASE 5: Code review (3 min)

Each task = meaningful unit of work

❌ WRONG - Too Granular:

Tasks:
  - PHASE 1: Ask user question 1
  - PHASE 1: Ask user question 2
  - PHASE 1: Ask user question 3
  - PHASE 2: Read file A
  - PHASE 2: Read file B
  - PHASE 2: Write file C
  - ... (50 micro-tasks)

Problem: Too many updates, clutters user interface
```

**Multi-Step Phases: Break Into 2-3 Sub-Tasks:**

For complex phases (>5 minutes), break into 2-3 sub-tasks:

```
✅ CORRECT - Sub-Task Breakdown:

PHASE 3: Implementation (15 min total)
  → Sub-tasks:
    - PHASE 3: Implement core logic (5 min)
    - PHASE 3: Add error handling (3 min)
    - PHASE 3: Write tests (7 min)

User sees progress within phase: "PHASE 3: 2/3 complete"

❌ WRONG - Single Monolithic Task:

PHASE 3: Implementation (15 min)
  → No sub-tasks

Problem: User sees "in_progress" for 15 min with no updates
```

**Avoid Too Many Tasks:**

Limit to **max 15-20 tasks** for readability:

```
✅ CORRECT - 12 Tasks (readable):

10-phase workflow:
  - PHASE 1: Ask user
  - PHASE 2: Plan (2 sub-tasks)
  - PHASE 3: Implement (3 sub-tasks)
  - PHASE 4: Test
  - PHASE 5: Review (2 sub-tasks)
  - PHASE 6: Fix issues
  - PHASE 7: Re-review
  - PHASE 8: Accept

Total: 12 tasks (clean, trackable)

❌ WRONG - 50 Tasks (overwhelming):

Every single action as separate task:
  - Read file 1
  - Read file 2
  - Write file 3
  - Run command 1
  - ... (50 tasks)

Problem: User overwhelmed, can't see forest for trees
```

**Guideline by Workflow Duration:**

```
Workflow Duration → Task Count:

< 5 minutes:    3-5 tasks
5-15 minutes:   8-12 tasks
15-30 minutes:  12-18 tasks
> 30 minutes:   15-20 tasks (if more, group into phases)

Example:
  5-minute workflow (3 phases):
    - PHASE 1: Prepare
    - PHASE 2: Execute
    - PHASE 3: Present
  Total: 3 tasks ✓

  20-minute workflow (6 phases):
    - PHASE 1: Ask user
    - PHASE 2: Plan (2 sub-tasks)
    - PHASE 3: Implement (3 sub-tasks)
    - PHASE 4: Test
    - PHASE 5: Review (2 sub-tasks)
    - PHASE 6: Accept
  Total: 11 tasks ✓
```

---

### Pattern 3: Status Transitions

**Exactly ONE Task In Progress at a Time:**

Maintain the invariant: **exactly one task in_progress** at any moment:

```
✅ CORRECT - One In-Progress:

State at time T1:
  [✓] PHASE 1: Ask user (completed)
  [✓] PHASE 2: Plan (completed)
  [→] PHASE 3: Implement (in_progress)  ← Only one
  [ ] PHASE 4: Test (pending)
  [ ] PHASE 5: Review (pending)

State at time T2 (after PHASE 3 completes):
  [✓] PHASE 1: Ask user (completed)
  [✓] PHASE 2: Plan (completed)
  [✓] PHASE 3: Implement (completed)
  [→] PHASE 4: Test (in_progress)  ← Only one
  [ ] PHASE 5: Review (pending)

❌ WRONG - Multiple In-Progress:

State:
  [✓] PHASE 1: Ask user (completed)
  [→] PHASE 2: Plan (in_progress)  ← Two in-progress?
  [→] PHASE 3: Implement (in_progress)  ← Confusing!
  [ ] PHASE 4: Test (pending)

Problem: User confused about current phase
```

**Status Transition Sequence:**

```
Lifecycle of a Task:

1. Created: pending
   (Task exists, not started yet)

2. Started: pending → in_progress
   (Mark as in_progress when starting work)

3. Completed: in_progress → completed
   (Mark as completed immediately after finishing)

4. Next task: Mark next task as in_progress
   (Continue to next task)

Example Timeline:

T=0s:  [→] Task 1 (in_progress), [ ] Task 2 (pending)
T=30s: [✓] Task 1 (completed),   [→] Task 2 (in_progress)
T=60s: [✓] Task 1 (completed),   [✓] Task 2 (completed)
```

**NEVER Batch Completions:**

Mark tasks completed **immediately** after finishing, not at end of phase:

```
✅ CORRECT - Immediate Updates:

Mark "PHASE 1: Ask user" as in_progress
... do work (30s) ...
Mark "PHASE 1: Ask user" as completed  ← Immediate

Mark "PHASE 1: Validate inputs" as in_progress
... do work (20s) ...
Mark "PHASE 1: Validate inputs" as completed  ← Immediate

User sees real-time progress

❌ WRONG - Batched Updates:

Mark "PHASE 1: Ask user" as in_progress
... do work (30s) ...

Mark "PHASE 1: Validate inputs" as in_progress
... do work (20s) ...

(At end of PHASE 1, batch update both to completed)

Problem: User doesn't see progress for 50s, thinks workflow is stuck
```

---

### Pattern 4: Real-Time Progress Tracking

**Update TodoWrite As Work Progresses:**

TodoWrite should reflect **current state**, not past state:

```
✅ CORRECT - Real-Time Up