---
name: writing-plans
description: Use before starting any non-trivial or multi-step piece of work — produce a clear plan BEFORE diving in. Triggers when the user asks you to plan, design an approach, scope an effort, or tackle work big enough to need ordered steps. The plan lives in a Scribe kind=plan task (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,
checkable list of steps — written *before* you start, so the approach is
reviewable and the work stays trackable.

## Start the plan in Scribe, not a file

For non-trivial work, call **`start_planning(project_id, title)` FIRST** —
before any design or implementation. It creates a `kind=plan` task seeded with a
template and returns the task id plus the project's applicable rules. The plan
lives in that task: edit the body with `update_task`, record progress with
`add_task_log`. **Do not** write plans or specs to local `.md` files — the task
is the record, not a file on disk.

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.
- **Approach** — the key design decisions and the trade-offs you chose, briefly.
- **Steps** — an ordered checklist, each step 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**: tick steps as they land; record decisions, findings,
  and pivots with `add_task_log` rather than silently rewriting the body.
- If reality diverges from the plan, **update the plan** — one that no longer
  matches what you're doing is worse than none.
- Set the plan task `in_progress` when you start and `done` when it's complete.

## Match depth to the work

A two-step change deserves a two-line plan; a multi-day effort deserves
milestones and sub-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.