---
name: writing-plans
description: Use when a piece of work has an arc — several steps toward one goal, worth tracking as a unit — and you want the approach reviewable before you start. Triggers when the user asks you to plan, design an approach, or scope an effort, or when work is about to sprawl across several steps. Not for single-step work. The plan lives in a Scribe milestone (via start_planning), not a local file.
---

# Writing plans

A plan is **how** you'll execute a chunk of work — the design plus an ordered
set of steps — written *before* you start, so the approach is reviewable and the
work stays trackable.

## First decide whether this work wants a plan

A plan lives in a milestone, and **a milestone earns its place when the work has
an arc**: several steps, one shared goal, a beginning and an end worth tracking
as a unit. That is the whole test, and it is a judgment about the *shape* of the
work — not about its size, difficulty, or importance.

Plenty of real work has no arc. A bug fix, a one-file change, a question
answered, a setting changed. For those, a milestone is a container with one
thing in it: the ceremony costs more than it records, and it leaves the project
with milestones that never meant anything. **Use a task instead** — set it
`in_progress`, record what you find with `add_task_log`, set it `done`. That is
a complete, honest record of work that didn't need a plan.

Some projects are milestone-shaped and some are a flat task list. Read the
project you are in rather than imposing a shape on it.

## When it does: start the plan in Scribe, not a file

Call **`start_planning(project_id, title)`** before designing or implementing —
so the milestone exists to write into, rather than being backfilled from work
already done. It creates a **milestone** (the plan container) seeded with a
design template and returns the milestone id plus the project's applicable
rules. The plan lives in that milestone:

- The **design/intent** goes in the milestone `body` — edit it with
  `update_milestone(milestone_id, body=...)`.
- Each **step** is its own task under the milestone — create it with
  `create_task(milestone_id=<that milestone>)` and track it with status +
  `add_task_log`. Steps are first-class tasks, **not** checkboxes in the body.
- Read the whole plan back with `get_milestone` (body + its step-tasks).

**Do not** write plans or specs to local `.md` files — the milestone is the
record, not a file on disk. (The old `kind=plan` task is retired; `start_planning`
no longer creates one.)

Before designing from scratch, **recall**: `search` Scribe for a related prior
plan or decision. Often the thinking (or half of it) already exists.

## What a good plan contains

- **Goal** — what "done" looks like, and why, in a sentence or two (milestone body).
- **Approach** — the key design decisions and the trade-offs you chose, briefly
  (milestone body).
- **Steps** — an ordered set of step-tasks under the milestone, each small enough
  to verify on its own; note which files/areas each touches.
- **Verification** — how you'll know it actually works (a test, CI, an
  observable behavior), not just "it's written."

## While executing

- Keep the plan **honest**: drive each step-task's status (todo →
  in_progress → done) as it lands; record decisions, findings, and pivots with
  `add_task_log` on the relevant step rather than silently rewriting the body.
- If reality diverges from the plan, **update the milestone body** — a design
  that no longer matches what you're doing is worse than none. Add or re-scope
  step-tasks as the work changes.
- Mark the milestone `done` when its steps are complete.

## Match depth to the work

A two-step change deserves a two-line plan; a multi-day effort deserves a
fleshed-out milestone body and several step-tasks. Don't over-plan the trivial,
and don't under-plan something that will sprawl. The point is a shared,
reviewable intent — not ceremony.