/milestone-planning

name: milestone-planning
description: Decomposes complex, multi-day tasks into optimized milestones (ultraplan). Broad parallel exploration grounds a draft milestone DAG, then independent adversarial critics attack the draft in rounds until no blocking findings remain. Triggers when the user says "plan milestones", "break this into milestones", "ultraplan", or when long-run harness needs milestone generation.

Milestone Planning (Ultraplan)

Decomposes a complex task into milestones in three moves: explore the codebase broadly in parallel, draft a milestone DAG grounded in what exploration found, then submit the draft to a panel of adversarial critics who attack it in rounds until it survives.

Core Principle

Milestones are the unit of long-running execution. A bad milestone decomposition cascades into days of wasted work. Two things prevent that:

• **Grounding.** The draft is built from actual codebase evidence gathered by parallel exploration — not from assumptions about what the code probably looks like.
• **Adversarial pressure.** Independent critics whose only job is to break the draft, before execution does it the expensive way.

A critic needs a concrete artifact to attack. This is why drafting comes before critique: "review the problem" produces suggestions; "break this draft" produces findings.

Hard Gates

1. **Explore before drafting.** Dispatch parallel exploration agents before composing the draft. Every milestone boundary must cite exploration evidence — a boundary not grounded in the actual codebase is an assumption, not a decision. 2. **All critics in a round run in parallel.** Dispatch every critic concurrently in a single message via the Agent tool. Sequential critique is prohibited. 3. **Every critic receives the full Problem Brief and the full draft.** Do not filter or slice per critic. 4. **Critics must not see each other's critiques.** Independence within a round is what makes agreement between critics meaningful. 5. **Every critique must be resolved explicitly.** Each finding is logged verbatim in the Critique Resolution Log and marked accepted (draft revised — say how) or rejected (with evidence-backed reason). Silently dropping a finding is a planning failure. 6. **Critique until dry.** After revising, dispatch a fresh critic round against the revised draft. The draft is locked only when a full round produces zero new Structural or Blocking findings. Maximum 3 rounds — Blocking findings still disputed after round 3 are escalated to the user with both sides stated. 7. **Every milestone must have binary-decidable success criteria.** "Working correctly" is not a criterion. Each criterion must be answerable met/not-met by running a command or reading code — the same standard as plan-crafting's Acceptance Criteria Rules. 8. **Milestone dependencies must form a DAG.** Circular dependencies are a plan failure. Every milestone must have a clear topological ordering. 9. **Do not generate milestones for trivial tasks.** If the problem can be solved in a single plan-crafting cycle (fewer than ~8 tasks), tell the user to use plan-crafting directly.

When To Use

• When the user presents a complex, multi-day task
• When the long-run harness needs milestone decomposition
• When the user says "plan milestones", "break this into milestones", or "ultraplan"
• When a task clearly requires multiple independent implementation phases

When NOT To Use

• Single-day tasks (use plan-crafting directly)
• Tasks with fewer than ~8 implementation steps
• When milestones are already defined and the user wants execution (use long-run)
• When work scope is still ambiguous (use clarification first)

Input

The skill requires a **clear problem statement** as input. This can come from:

1. A Context Brief file produced by the `clarification` skill (preferred) 2. A direct, detailed request from the user (must include goal, scope, constraints)

If the input is ambiguous, return to the `clarification` skill before proceeding.

Process

Phase 1: Problem Framing + Broad Exploration

1. Read the input (Context Brief or user request) 2. Identify: goal, scope boundaries, technical constraints, success criteria 3. **Dispatch parallel exploration agents** — several read-only Explore subagents concurrently, each with a distinct lens:

• **Architecture & interfaces:** modules, boundaries, and contracts the work will touch; existing patterns to follow
• **Dependencies & data flow:** what depends on what; shared state (DB schemas, config, globals); external systems and their setup requirements
• **Verification landscape:** e2e tests, integration tests, test suites, CI checks — this feeds the Verification Strategy
• **Conventions & history:** naming and structural conventions, recent related changes, prior attempts at similar work

Add task-specific lenses when the problem calls for them (a schema/migration lens for data work, an auth/permissions lens for security-touching work, a client-compat lens for API changes). 4. Compose the **Problem Brief** — self-contained; both the draft and every critic will receive it:

## Problem Brief

**Goal:** [What must be achieved]

**Scope:**
- In: [What is included]
- Out: [What is explicitly excluded]

**Technical Context:**
[Relevant architecture, existing code, constraints]

**Exploration Digest:**
[Key findings per lens, with file references — this is the evidence base
 the draft cites and the critics check against]

**Constraints:**
[Time, compatibility, dependencies, performance requirements]

**Success Criteria:**
[Binary-decidable outcomes]

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

**Verification Discovery:** Use the same discovery order as plan-crafting (e2e → integration → verification skills/agents → test suite → build+lint)