write-plan git:20261022.d0898d5A

Immutable. This exact content never changes and is served at /api/v1/blob/5331e06a08ddfb27.

---
name: write-plan
description: Use when something non-trivial is to be built or reworked and its implementation plan has to be written, from an idea or from a board, or when a plan has to be redrawn after an increment landed. Produces, through an interview, the one plan document that holds the design, the decisions, the slices, the tracker execute-plan runs from and the orchestrator's mandate. Not for keeping an open discussion (brainstorm), not for cutting the slices or writing their documents (write-slice) and not for carrying the plan out (execute-plan).
---

# Write a plan

**One document holds the design and the plan.** What the interview settles is written
once, there, and each slice carries its part of it verbatim, narrowed to its scope.

**The plan is written for an agent that was not in the conversation.** Read alone, it gives
every decision, its reason and every detail the work needs, so that agent is as aligned as
the person and you are now. Nothing settled lives only in the chat.

**No code in the repository for the thing being planned until the plan is approved.**

1. **Open `YYYY-MM-DD-<topic>.plan.md` before the first question**, through the `aiview` skill: kind `plan`, tags = topic, in the group aiview gives a plan, shared with its slices. With a roadmap, the slot's slug is a tag. Its two parts, Design and Execution, are `references/skeleton.md`, read before writing the first section. A board on the topic is the starting point: its agreed decisions become rows, numbered in this plan with the board's id in their source (`board <topic>.board#D2`), and are not asked again.
2. **Run the `interview` skill** on the decisions table, and write each section as its decisions land. If the person declines it, offer its short mode; a decision still unasked is a row with source `agent default`. A request that is several independent systems is split first, one plan each. One plan per increment: it stops where the next increment would begin.
3. **Every major area is a deep module**, designed as the `deepen-module` skill says, in the plan's modules section. A module the interview cannot settle there gets its own `module` document, and the plan quotes its entry.
4. **When no row is open, ask once what else this should cover.**
5. **Ask the mode before the cut**, recommending the one the work fits, first: `mode: swarm`, N seats working the plan phase by phase, coordinating on the board of the `swarm` skill, recommended when the work has room for two seats or more at once; or `mode: classic`, the slices run one after another and forks proved apart, recommended for a small or strictly sequential change. The answer is the mandate's first field; swarm then asks `phases:`, `seats:` and `verify:`, one per message, as the `orchestrate-plan` skill's `references/mandate.md` says. **In swarm mode, read `references/swarm.md` now**: it adds the seats and the phases, and changes the cut, the tracker and when the slice documents are written.
6. **Cut the slices** as the `write-slice` skill's `references/cutting.md` says, **and draw the tracker** to `references/tracker.md`, from `references/tracker-skeleton.md`, both read first. The `execute-plan` skill keeps it from then on. `aiview mermaid-check <plan>`, `aiview tracker check <plan>` and `scripts/decisions.mjs <the plan's folder>` after every edit: the last says whether a topic, an id or a citation collides or points nowhere.
7. **Before the mandate, dispatch a fresh subagent on the `cold-read` skill**, with the plan's id and none of the conversation; discuss with it as a peer, explaining your intent and asking how it read each part, until you understand each other; every point you settle goes into the plan, and it re-reads until it says `ready`.
8. **Close the interview with the orchestrator's mandate**: the questions of the `orchestrate-plan` skill's `references/mandate.md`, the answers in the plan's *Mandate* section and in the one line under the tracker. An answer that changes the cut, `tests: at the plan end`, is carried out then, as that reference says: the test slice drawn, the slice headings following. Whatever the mandate changed in the plan, the cold reader re-reads, until it says `ready` again.
9. **Stop and ask the person to approve the plan.** The request opens on the `agent default` rows, numbered, `contract` ones first, "4 decisions are mine: … confirm them, or name the ones to change", and the link to the plan comes after the list. The approval goes in the status line with the defaults it confirmed, then `aiview plan check <plan>`. Then one slice document per slice, with `write-slice`; in swarm mode, none: each is written at its phase's open.

## Red flags

| Thought | Reality |
|---|---|
| "I'll plan the whole feature while I have the context" | The next plan is written with this increment's learning in hand, which you do not have yet. |