Milestone Planning: Breaking Large Work into Manageable Phases

Guidance for decomposing complex features and refactors into verifiable milestones.

The Problem

Large features kill context:

• No clear checkpoints for verification
• Hard to track progress
• Difficult to recover from errors
• Context fills with noise

The Solution: Vision → Roadmap → Milestones

Vision (1-2 sentences: what we're building)
    │
    ├─ Roadmap (3-7 major phases)
    │
    └─ Milestones (Verifiable increments)
        │
        └─ Tasks (Implementer-sized units)

Vision Statement

Purpose: Describe the overall goal in 1-2 sentences.

Good: "Add real-time collaboration using WebSockets" Bad: "Make the app better" (too vague)

Roadmap

Purpose: Identify 3-7 major phases that build toward the vision.

Principles:

• Each phase has clear dependencies
• Earlier phases enable later ones
• Each delivers incremental value

Example: WebSocket collaboration → 1) Server infrastructure, 2) Client connection, 3) Sync protocol, 4) UI presence, 5) Conflict resolution

Milestones

Purpose: Break each roadmap phase into verifiable increments that fit in context.

Sizing Rules

Must fit: 10-15 tasks, 2-4 hours, verifiable end state, shippable code Typically: 5-15 files, 500-2000 LOC, 1-3 abstractions, 3-5 commits

When to Split/Combine

Split if: > 15 tasks, multiple patterns, > 4 hours, unclear end state Combine if: Each < 5 tasks, strong coupling, combined fits rules

Milestone Template

## Milestone N: [Name]

**Goal:** [1 sentence]

**Exit criteria:**
- [ ] Tests pass
- [ ] Feature works as specified
- [ ] Documentation updated

**Dependencies:** Milestone X complete

**Tasks:** (see /task-sizing)
1. Task description
2. Task description

**Out of scope:** [What we're NOT doing]

Milestone Ordering Strategies

Bottom-up (Infrastructure First): Foundation → features. Use for new systems, refactors. Top-down (UI First): UI → stubs → implementation. Use for features, prototypes. Vertical Slices: Narrow complete feature → expand. Use for complex/uncertain work.

Progress Tracking

After each milestone:

1. Run full test suite
2. Verify against exit criteria
3. Update roadmap document
4. Start fresh context for next milestone

State persists in .harness/state.json.

Common Pitfalls

Too granular (30+ milestones): Planning overhead exceeds value Too coarse (2-3 milestones): Context bloat, mini-projects No dependencies: Suggests poor decomposition Linear waterfall: No parallelization opportunities

Related Skills

• /agile-workflow - Overall methodology
• /task-sizing - Breaking milestones into tasks
• /context-health - Managing context between milestones