writing-plans

Writing Plans

A plan is only useful if it's specific enough that a stranger could execute it without asking questions.

When to Activate

• Creating a plan for a feature that touches more than 2 files
• Planning a refactor where the sequence of steps matters
• Designing a database migration or schema change
• Writing a plan to hand off to a subagent for implementation
• Any task where "implement X" is too vague to be actionable
• Planning work that requires specific test commands or rollback steps
• Onboarding a contributor to an ongoing task mid-stream

The Zero-Placeholder Rule

Every element of a plan must be fully specified. If you write it, it must be complete — no fill-in-the-blank, no ellipsis, no "implement as needed."

Plan Structure

## Goal
One sentence: what this plan achieves and why.

## Pre-conditions
- [ ] Specific thing that must be true before starting: `command` → expected output
- [ ] Environment variable or service that must be running

## Steps

### Step 1 — <verb> <specific target>
**File:** `absolute/path/to/file.ext`

\`\`\`language
// Full code block — no ellipsis, no "rest of function", no TODO comments
\`\`\`

**Verify:** `exact command` → `expected output`

### Step 2 — commit checkpoint
**Commit:** `type(scope): specific description of what changed`

## Rollback
- If step 3 fails: `exact command to undo`
- If migration was applied: `alembic downgrade -1`