# Writing Plans

Audience: AI coding agents first. Optimize for activation, not aesthetics.

Write a **request spec** for the factory: what to build, against which seams, and how to know it worked. The factory's own planner decomposes it into steps and its builder writes the code.

**Save to:** `docs/plans/YYYY-MM-DD-<PLAN_SLUG>.md` (user preference overrides).

`PLAN_SLUG` = kebab key. Invoked by brainstorm → use the slug it passed. Standalone → derive one from the feature.

## The one rule that governs every section

**Pin the CONTRACT, never the implementation body.** The builder writes the body for free by reading the repo; a body written here is paid-for work that gets re-derived and re-reviewed — triple cost.

Collapse to literal code ONLY when the code is shorter than the prose describing it (a one-line guard, a constant, a typo). Then paste the code; a contract for it is pure overhead.

```
impl_LOC ≤ contract_LOC ?
  ── yes → paste the literal code
  ── no  → contract only (seam + behavior + acceptance)
```

**NEVER author a task graph, a dependency table, per-step checkboxes, or an ordering.** The factory's planner produces those from this document. Writing them here duplicates work that gets thrown away and invites the two to drift.

## Scope check

Spec covers multiple independent subsystems → split into one request doc per subsystem. Each must produce working, testable software standalone.

## Document shape

```markdown
# <Feature> — request

**Goal:** one sentence.

**Context:** what exists today that this changes, with real paths.

**Files:**
- Create `exact/path/to/file.ts` — one-line responsibility
- Modify `exact/path/to/existing.ts:123-145` — what changes

**Contract:**
- Signature: `function name(input: InputType): ResultType`
- Types: `InputType = {...}` (or point to where it is defined)
- Route / schema / IO shape; any spec-mandated literal string verbatim

**Behavior:** what it must do. The named edge cases. The named error conditions.

**Out of scope:** what the factory must NOT touch.

**Acceptance:**
- Run: `pnpm --filter web test src/path/thing.test.ts`
- Expected: PASS — `name(sample) === expected`
```

Scale the sections to the work. A one-file change does not need a Context paragraph.

## Precise contract, not vague prose

Contract-level ≠ vague. Pin the seam exactly; leave only the body downstream.

**Vagueness — NEVER write:**
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases" → name the exact errors, validations and edge cases
- "Write tests for the above" with no acceptance criterion → give the command and its expected output
- A reference to a type, function or method whose signature appears in no Contract and does not already exist in the repo

**Body bloat — NEVER write:**
- A substantial implementation body when the contract is shorter
- Full unit-test bodies — give the acceptance command and the behavior
- A before/after diff of an existing file — describe the seam it becomes and the behavior delta

## Remember

- Exact file paths always.
- Exact commands with expected output.
- Spec mandates an exact string or format → paste it verbatim. NEVER say "similar to the spec".
- Name what is out of scope. An unbounded request produces an unbounded diff.

## Self-review

Fresh eyes on the finished doc. Run it yourself, not in a subagent.

1. **Coverage** — skim each spec requirement; can you point at the part of this doc that demands it? List gaps and fix them.
2. **Vagueness + body bloat** — scan for the red flags above. Strip any body whose contract would be shorter.
3. **Seam consistency** — every signature, type and property name matches across sections and matches the repo. `clearLayers()` in one place and `clearFullLayers()` in another is a bug. Every type used is defined here or already exists.

Fix inline. No re-review.

## Launch

After saving, launch it:

```bash
cd <repoRoot> && factory adw_plan_build_test_quality docs/plans/YYYY-MM-DD-<PLAN_SLUG>.md
```

Tell the user the run is autonomous and streams to the `/factory` page in the overdeck web UI.