writing-plans

Writing plans

A plan turns a reviewed spec into chunks an executor can dispatch. Each chunk is a self-contained unit of work with a declared touch list (files + symbols) that drift detection measures actual changes against.

When you're done

plan.md and plan.tracker.json exist. Every chunk has: stable chunk:N flags in the body, a tracker entry with status: "pending", a non-empty touched.declared.files, and dependencies recorded if any. You've offered to invoke dispatching-chunks.

Process

1. Read the spec. Every section. Pull the goal, non-goals, design, constraints. Note success criteria — every one should map to at least one chunk.
2. Map the file structure. Before defining chunks, list every file you expect to create or modify and its responsibility. Lock decomposition decisions here.
3. Decompose into chunks. Each chunk should be one shippable, testable unit. 2–8 chunks is typical; > 12 chunks usually means the spec should have been a roadmap.
4. For each chunk, declare: title, depends-on (other chunk ordinals), declared touch list (files always; symbols when known), test approach.
5. Write plan.md. Header + chunked body using the structure below.
6. Write plan.tracker.json. kind: "plan", populate chunks with declared touch lists, drift_propagation: { version: 0, last_dispatched_chunk: null }. If the plan rolls up to a roadmap row, populate roadmap.
7. Self-review. Spec-coverage scan (every success criterion → a chunk), placeholder scan, type-consistency scan (a function called foo in chunk 3 and foo_bar in chunk 7 is a bug). Fix inline.
8. Hand off. Offer dispatching-chunks. Stop. Do not dispatch yourself, and do not mention any commit/dispatch script — the user runs dispatch when they're ready.

Plan body and tracker structure

You MUST scaffold the plan via dev-pipeline.js plan-from. Do not hand-write the structure; do not adapt a prior plan. The plan-from verb copies the canonical templates next to the spec and surfaces section IDs likely to drive chunks. The templates are the single source of truth for chunk flag syntax, the required per-chunk structure (Goal/Depends on/Read first/Touched files/Touched symbols/Steps), and the tracker schema. dispatching-chunks reads chunks by chunk:N flag and looks up the declared touch list in the tracker by ordinal — a hand-written plan that drifts will fail to dispatch.

node greymatter/scripts/dev-pipeline.js plan-from <init>/spec.md

This writes <init>/plan.md and <init>/plan.tracker.json (kind: "plan", two example chunks at status: "pending", drift_propagation.version: 0). Then populate. The body template ships two example chunks wrapped in chunk:N flags, each with the full required structure. The Read-first block in chunk 1 demonstrates the symbol > flag > line-range hierarchy in a real example. The tracker template ships kind: "plan" with the matching two chunks at status: "pending" and drift_propagation.version: 0.

Renumbering chunks requires updating both the body flags AND the tracker keys in the same change. Every chunk in the body MUST have a tracker entry; every tracker entry MUST have a body flag. Mismatch is a validator error.

Chunk granularity

• Each step is one action (2–5 minutes): "write the failing test," "run it to confirm failure," "implement minimal," "run tests," (no commit step — the user owns commits).
• Each chunk is self-contained. A reader of chunk 5 should not need to read chunks 1–4. Repeat function signatures inline rather than referencing earlier chunks.
• Final step of every chunk is the exception-only observations check: append a one-liner to observations.md if a later chunk needs the heads-up; otherwise skip. Declared/actual drift is measured mechanically by completing-chunks.

Targeted reads — non-negotiable

Greymatter's token economics depend on never reading more than necessary. Every Read first entry must use the most stable reference available. The hierarchy:

1. Code symbols → name-addressed via the graph. get_node_bundle <project> <file> <symbol> returns the symbol body, its 1-hop edges, and its labels in one call. The symbol name is the stable handle — it survives any line-shift in the file, exactly the way pipeline flags survive body edits. This is the default for any reference to a named function, class, method, or type.
2. Pipeline artifacts → flag references. spec.md §3 (via <!-- section:3 -->), plan.md chunk 5 (via <!-- chunk:5 -->), roadmap.md row foundation (via <!-- decision:1 -->). Flags are line-stable; line ranges drift the moment the body is edited.
3. Line ranges → fallback only. Use only when (1) and (2) don't apply: file headers, imports, config blocks, raw text without flags, language constructs that aren't named symbols. Format: <path>:L<start>-L<end> — <why this range>. Never "read the whole file."

Per-task spec citations: every task that implements a spec requirement names the section by flag. (per spec §3) or (per spec §3, "Validator behavior"). Makes "is this chunk faithful to the spec?" a one-glance check that doesn't break when the spec body is edited.

A Read first entry that uses a line range when a symbol or flag was available is a plan failure — reviewers will reject it. Line ranges accumulate edit-debt; symbols and flags don't.

No placeholders

Steps that say "add error handling," "write tests for the above," "similar to chunk N," or "implement X" without showing the code are plan failures. Every code step shows the code. Every command step shows the command and the expected output.

Chunk-body code blocks are illustrative

Code shown in a chunk body is a contract on what changes — function signatures, exported names, the shape of the diff. It is not prescriptive on local statement ordering. When a chunk body's example says "amend X — at the end, before Y," the executor may invert local ordering when atomicity or readability calls for it. If the deviation could mislead a later chunk, the executor flags it in observations.md; otherwise it's silent. Reviewers should not flag local re-ordering as drift unless the change alters externally observable behavior.

Anti-patterns

• Editing chunk numbers manually. Renumbering requires the tracker to be updated in the same change. Use a fresh ordinal at the end before reordering.
• Chunk too big. If a chunk's declared touch list spans more than ~5 files, split it.
• Skipping declared symbols when known. Symbol-level drift detection (graph diff) is the whole point. File-only declarations work but lose half the signal.
• Read first: lib/foo.js with no symbol, flag, or range. The whole point of greymatter is targeted reads — a chunk that tells the executor to read a 600-line file wastes tokens by design.
• Line ranges where a symbol would do. lib/foo.js:L42-L78 for a function that has a name (processInput) is brittle — the line numbers drift on the next edit. get_node_bundle <project> lib/foo.js processInput doesn't.
• Mentioning commits, the dispatch script, or npm run anything in the handoff. The user runs those.