plan

What this skill does

# Structured Planning

Verification-driven task decomposition with Sibyl-native tracking. Mined from 200+ real planning sessions: the plans that actually survived contact with code.

**Core insight:** Plans fail when steps can't be verified. Decomposition that lands in concrete checks survives contact with reality; abstract bullets don't. Tracking in Sibyl lets plans outlive the context window that produced them.

**How to read this skill:** the phases below describe the rhythm of a useful planning pass, not a procedure to march through. Skip planning entirely for small clear work, compress phases when the answers are obvious, and treat the first plan as a hypothesis. Replanning is the rule, not the exception.

## The Shape

```dot
digraph planning {
    rankdir=TB;
    node [shape=box];

    "1. SCOPE" [style=filled, fillcolor="#e8e8ff"];
    "2. EXPLORE" [style=filled, fillcolor="#ffe8e8"];
    "3. DECOMPOSE" [style=filled, fillcolor="#e8ffe8"];
    "4. VERIFY & APPROVE" [style=filled, fillcolor="#fff8e0"];
    "5. TRACK" [style=filled, fillcolor="#e8e8ff"];

    "1. SCOPE" -> "2. EXPLORE";
    "2. EXPLORE" -> "3. DECOMPOSE";
    "3. DECOMPOSE" -> "4. VERIFY & APPROVE";
    "4. VERIFY & APPROVE" -> "5. TRACK";
    "4. VERIFY & APPROVE" -> "3. DECOMPOSE" [label="gaps found", style=dashed];
}
```

---

## Phase 1: SCOPE

Bound the work before decomposing it. The goal is calibrating planning depth to actual scope, not generating a deliverable.

### Common moves

- **Search Sibyl** for related tasks, decisions, and prior plans: `sibyl search "<feature keywords>"`, `sibyl task list -s todo`. Cheap and often surfaces an already-decomposed predecessor.
- **Define success criteria** in measurable terms ("tests pass", "endpoint returns X", "p95 latency < 200ms") instead of vague goals like "improve performance".
- **Identify constraints**: files that shouldn't change, dependencies to respect, timeline or budget pressure.
- **Calibrate planning depth** to scope:

  | Scale         | Description                | Planning depth             |
  | ------------- | -------------------------- | -------------------------- |
  | **Quick fix** | < 3 files, clear solution  | Skip planning, go build    |
  | **Feature**   | 3-10 files, known patterns | Light plan (this skill)    |
  | **Epic**      | 10+ files, new patterns    | Full plan + orchestration  |
  | **Redesign**  | Architecture change        | Full plan + research first |

If the work is a quick fix, stop planning and go build. Planning a five-minute change is pure overhead.

---

## Phase 2: EXPLORE

Understand the codebase surface before decomposing it. Plans built from filenames alone fall apart at contact with the actual code.

### Common moves

- **Map the impact surface**: which files and modules will this touch? Read the actual code rather than guessing from names; spawn an Explore agent when scope is genuinely uncertain.
- **Identify existing patterns**: how does similar functionality already work? What conventions apply (naming, file structure, test patterns)?
- **Trace dependencies**: what must exist before this can work, and what breaks if we change X?

You're aiming for a mental model you can articulate: "this touches module A (new endpoint), module B (type changes), module C (tests); pattern follows existing feature X; depends on infrastructure Y being available." If you can't write that sentence, decomposition will rest on guesses.

---

## Phase 3: DECOMPOSE

Break the work into steps you can actually verify. The discipline that separates plans-that-survive from plans-that-fail is connecting each step to a concrete check.

### Measure twice: look for the reframe first

The most expensive plan is one that faithfully decomposes the wrong shape: tidy tasks, clean DAG, all building something that didn't need to exist. Before breaking work down, spend one pass hunting the judo move that shrinks it.

- **Can a reframe collapse the task list?** A different shape might turn ten tasks into three. Reframe before you decompose, not after you've built.
- **Does the codebase already own this?** Reusing an existing pattern, module, or canonical helper beats decomposing a bespoke build of the same thing.
- **What can we not build?** The cheapest task is the one you strike from the plan. Delete a mode, a layer, a config surface rather than scheduling work to construct it.

Measure twice, cut once: confirm this is the simplest shape, then decompose it.

### The verification heuristic

A step without a verification method is a hope, not a step. Push every task toward a concrete check before considering it decomposed. For each task, the useful fields are:

| Field          | Description                     |
| -------------- | ------------------------------- |
| **What**       | Specific implementation action  |
| **Files**      | Exact files to create/modify    |
| **Verify**     | How to confirm it works         |
| **Depends on** | Which tasks must complete first |

### Verification Methods

| Method        | When to Use                              |
| ------------- | ---------------------------------------- |
| `typecheck`   | Type changes, interface additions        |
| `test`        | Logic, edge cases, integrations          |
| `lint`        | Style, formatting, import order          |
| `build`       | Build system changes                     |
| `visual`      | UI changes (screenshot or browser check) |
| `curl/httpie` | API endpoint changes                     |
| `manual`      | Only when no automation exists           |

### Decomposition heuristics

- **2-5 minute tasks** tend to be the sweet spot. Tasks running longer than 15 minutes usually deserve to be split.
- **One concern per task.** "Add endpoint AND write tests" is two tasks; treat conjunctions in task titles as splitting hints.
- **Order by dependency, not difficulty.** Foundation first; later tasks build on earlier ones.
- **Mark parallelizable tasks.** Tasks with no shared files can run simultaneously, which matters once you hand off to orchestration.

### Task Format

```markdown
## Task [N]: [Imperative title]

**Files:** `src/path/file.ts`, `tests/path/file.test.ts`
**Depends on:** Task [M]
**Parallel:** Yes/No (can run alongside Task [X])

### Implementation

[2-4 bullet points of what to do]

### Verify

- [ ] `pnpm typecheck` passes
- [ ] `pnpm test -- file.test.ts` passes
- [ ] [specific assertion about behavior]
```

### Parallelizability Markers

Mark tasks that can run simultaneously for orchestration:

```
Wave 1 (foundation):  Task 1, Task 2  [parallel]
Wave 2 (core):        Task 3, Task 4  [parallel, depends on Wave 1]
Wave 3 (integration): Task 5          [sequential, depends on Wave 2]
Wave 4 (polish):      Task 6, Task 7  [parallel, depends on Wave 3]
```

---

## Phase 4: VERIFY & APPROVE

Sanity-check the plan before presenting it. The goal isn't ceremony; it's catching the obvious failure modes that turn plans into churn.

### Worth confirming before presenting

- Every task has a verification method (the most common gap)
- Dependencies form a DAG, no cycles
- No two parallel tasks touch the same files
- Total scope still matches the success criteria from Phase 1
- Nothing snuck in that you don't actually need yet (YAGNI)
- No task survives that a reframe could delete (the judo check from Phase 3)

### Present for Approval

Show the plan as a structured list with waves:

```markdown
## Plan: [Feature Name]

**Success criteria:** [measurable outcome]
**Estimated tasks:** [N] across [M] waves
**Parallelizable:** [X]% of tasks can run in parallel

### Wave 1: Foundation

- [ ] Task 1: [title] → verify: [method]
- [ ] Task 2: [title] → verify: [method]

### Wave 2: Core Implementation

- [ ] Task 3: [title] → verify: [method] (depends: 1)
- [ ] Task 4: [title] → verify: [method] (depends: 2)

### Wave 3: Integration

- [ ] Task 5: [title] → verify: [method] (depends: 3, 4)
```

### Gap analysis

Once the plan is on the