Write Plans

Write Plans

Overview

Write an implementation plan for an engineer who has zero context for this codebase and questionable taste. They are a skilled developer, but they know almost nothing about our toolset or problem domain, and they don't know good test design very well. Document everything they need: which files to touch for each task, complete code, which docs to check, and exactly how to test it.

This matters doubly because plans are executed by /implement, which hands each task to a fresh subagent with no conversation context. The task text is the subagent's entire briefing — anything you leave out doesn't exist for it, and any gap gets filled with a guess.

Announce at start: "I'm using the write-plans skill to create the implementation plan." Add "— human mode" when --human is in play, so the reader knows why the plan looks different.

Principles: DRY. YAGNI. TDD. Frequent commits. Exact paths, complete code, exact commands.

Modes

• Default — the plan is written for /implement's subagents and nobody else.
• --human — one plan, same path, still executed by /implement verbatim; it just gains the sections a person needs to judge the approach without reading every code block. Use it when the user passes --human, or when the plan goes to someone else for approval before implementation.

Human mode adds sections, it never trims them. The code, commands, and expected output stay complete — a plan that reads well but under-briefs the subagent has failed at its main job.

Inputs — the plan captures decisions, it doesn't make them

Find the settled decisions, in this order:

1. Grill session in this conversation (/grill-me, /grill-with-docs) — use the final decisions verbatim. Don't re-litigate anything already decided.
2. Design document — a doc in docs/designs/ the user points at (or the obvious recent one).
3. Neither, or gaps remain — run a mini-grill before planning: interview /grilling-style (one question at a time, with your recommended answer; explore the codebase instead of asking when the code can answer). Continue until every decision the plan depends on is settled. Never plan on top of an unstated assumption.

Workflow

1. Gather decisions (above).
2. Explore the codebase — silently read every file the plan will touch. Find existing patterns, utilities, and test conventions to reuse (DRY). Collect exact paths, line numbers, and the real commands for running tests, typechecking, and building.
3. Draft the plan and present it to the user for review before saving.
4. Save to docs/plans/YYYY-MM-DD-<feature-name>.md (get the date from date +%Y-%m-%d).
5. Plain-language pass (--human only) — the final step. Rewrite the saved plan's prose per the section below, then overwrite the file.

Plain-language pass (--human only)

Run this last, once the plan is saved. A --human plan is read by a person, so its prose should read plainly. Rewrite the saved plan's prose into short sentences and everyday words — the Overview, Architecture, Why this approach, Tasks at a glance descriptions, and each task's Context and What & why. Write in the same language as the rest of the plan.

Rewrite prose only. Reproduce every fenced code block (including the mermaid diagram), every command, every expected-output line, and the YAML frontmatter exactly — a reworded command is a broken plan. Keep every fact, name, number, link, and file path, and keep all Markdown structure (headings, lists, tables, links). Aim for a reviewer who understands the change without reading a single code block.

Plan Document Structure

Header

Every plan starts with this header:

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use /implement to execute this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about the approach]

**Toolset:** [Exact commands the engineer needs: run one test file, run the full suite, typecheck, build]

**Read first:** [Docs, README sections, or reference files the engineer should read before starting — with paths/links and one line on why each matters]

---

Header — --human additions

The header's one-line **Architecture:** field is promoted to a full section, and two sections join it. All three sit between the header and Task 1, in this order.

## Architecture — the diagram first, then the 2-3 sentences that were the header field. Default to mermaid: flowchart for components and data flow, sequenceDiagram for a request lifecycle, erDiagram for schema changes. Use ASCII when the shape is a few boxes and an arrow, or when the doc will be read where mermaid doesn't render. Label nodes with the real module, file, or service names — not "Service A". Mark what's new versus what already exists, so the reviewer sees the size of the change at a glance. If you can't draw it, you don't understand it well enough to plan it.

## Why this approach — the decisions the plan rests on, one line each, with what was rejected and why. Take these from the grill session or design doc; don't invent tradeoffs the user never weighed. This is the section a reviewer disagrees with, so it earns its place — everything downstream is a consequence of it.

## Tasks at a glance — a table with task number, one-line description, main files, and risk. The diagram plus this table is the whole review surface: a reviewer who reads only those two should be able to say yes or no.

Tasks

Break the work into bite-sized tasks, ordered sequentially. A task is one coherent change that ends in a passing test suite and a commit — small enough that a reviewer can hold the whole diff in their head.

Test-first ordering: the failing test comes before the implementation, within each task and across the plan. If the feature needs e2e or integration tests, writing those is Task 1.

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file`
- Modify: `exact/path/to/existing:line_range`
- Test: `tests/exact/path/to/test`

**Context:** [What the engineer must know before touching anything: domain terms
explained, existing patterns to mimic (with file paths), docs to check, gotchas]

**Step 1: Write the failing test**

[Complete test code. The engineer doesn't know good test design — give them the
exact tests and say in one line what each test proves.]

**Step 2: Run the test to verify it fails**

Run: `[exact command]`
Expected: FAIL with "[expected error]"

**Step 3: Write the implementation**

[Complete implementation code]

**Step 4: Run the test to verify it passes**

Run: `[exact command]`
Expected: PASS

**Step 5: Commit**

Run: `git add [files] && git commit -m "[message]"`

In --human mode, each task gains a What & why line above Files: one or two sentences on what this task changes and why it sits at this point in the order. Everything else about the task is unchanged. Add a task-level diagram only where the prose genuinely can't carry the shape — a state machine, a multi-service handshake — not by default.

Not every task follows the TDD cycle (config changes, migrations, docs) — adapt the steps, but always give complete code and exact commands with expected output. "Add validation" is not a step; the validation code is.

Use the /tdd-it skill to design the tests for any test-writing task rather than hand-rolling test scaffolding.

Handoff

After saving, tell the user: "Plan saved to <path>. Ready to execute it with /implement?"

Remember

• Exact file paths, always
• Complete code in the plan, never a description of code
• Exact commands with expected output
• Each task ends in a commit
• --human adds the diagram, the rationale, and the task table, and rewrites the prose in plain language — it removes nothing
• DRY, YAGNI, TDD