# plan — Manual

## What it does
Runs the planner over the live session: it decomposes the goal into milestones and steps (each tagged with an executor — `TOOL`, `AGENT` or `SELF`) and **populates the todo with those steps**. It reads the conversation, memory, the todo and the scratchpad's `findings`/`errors` sections, so a re-plan sees what you have already learned.

It costs **2 LLM calls** (complexity analysis + execution plan). Use it selectively, like `reflect`.

Requires an active agent run — outside one the call fails with *plan is not available in this context*.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `reason` | for re-planning | What changed — the discovery that makes the current plan stale, in one or two concrete sentences. |
| `updated_goal` | no | The new success criterion, only meaningful together with `reason`. |

```json
{}
{"reason": "the config is TOML, not JSON, so the parser step is wrong"}
{"reason": "the API needs pagination after all", "updated_goal": "sync all 12k records, not just the first page"}
```

## When to call it

Call it **before** starting execution when the task is non-trivial:

- multiple steps, or several files/systems involved;
- research or an unknown codebase, where the shape of the work is itself unclear;
- real risk — production, data loss, irreversible operations;
- the work needs sub-agent scoping decided up front.

Skip it for trivial work: a single-file edit, a one-off command, a question, casual chat. Planning a one-liner wastes two LLM calls and produces a plan of one step.

## Re-planning

Pass `reason` when the plan's **overall structure** is wrong — a step turned out unnecessary, the real problem differs from the assumed one, or new constraints appeared. The new plan replaces the todo; completed work survives in the conversation and the scratchpad.

Do **not** re-plan for a single failed step, or to drop/merge/reorder one or two steps — edit the `todo` directly with `add`/`update`. The choice between the two tools:

| Situation | Tool |
|---|---|
| One step failed, or the order of a couple of steps changed | `todo` |
| You are unsure *what* is wrong; the approach needs questioning | `reflect` |
| The remaining plan's overall shape is wrong, or there is no plan | `plan` |

## What you get back

`# Plan` (fresh) or `# Revised plan` (with `reason`), followed by the milestones and steps, followed by an instruction that depends on the assessed complexity:

- **complex** — present the plan to the user in a few sentences and **wait for confirmation** before executing. Do not start yet.
- **not complex** — the todo has been populated; proceed from step 1, tracking progress with `todo`.

When planning produces no plan at all, the call fails rather than inventing one: proceed directly (fresh) or keep the current plan and revise the todo inline (re-plan). Neither is an error to retry.

## Rules

- One plan per task. Calling it again mid-task without `reason` throws away the current plan and its progress.
- After a re-plan the todo reflects the new plan — the old steps are gone; do not `update` an index that no longer means what it did.
- The plan is not a substitute for doing the work: nothing in it is executed by calling it.