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`

Sequencing Rules

Forbidden Patterns

# BAD — relative path
Update the config in `settings.py`

# GOOD — absolute path
Update `src/config/settings.py` (absolute from repo root)

# BAD — vague instruction
Add error handling to the endpoint

# GOOD — complete instruction
In `src/api/routes/users.py` line 47, wrap the db.query() call:

try:
    result = db.query(User).filter(User.id == user_id).first()
except SQLAlchemyError as e:
    logger.error("db_query_failed", user_id=user_id, error=str(e))
    raise HTTPException(status_code=500, detail="Internal server error")

# BAD — no expected output
Run the tests to verify everything works.

# GOOD — exact command + expected output
$ pytest tests/api/test_users.py -v
PASSED tests/api/test_users.py::test_get_user_returns_404_when_not_found
PASSED tests/api/test_users.py::test_get_user_returns_user_data
2 passed in 0.43s

When to Plan vs. When to Code

Red Flags

• "Implement X" as a plan step — this is a task description, not a plan; expand into specific files, code, and verify commands
• Relative file paths — ambiguous across machines and working directories; always specify paths from a known root
• No verify step after a destructive operation — you won't know it succeeded until something later fails unexpectedly
• Bundled steps ("do A and B and C together") — if B fails, you can't tell what state A left the system in
• Missing rollback for irreversible steps — database migrations, published events, external API calls all need explicit undo instructions
• "Add tests" without specifying which file, which test case, and what the assertion checks
• Missing pre-conditions — forgetting to list required services, env vars, or setup that must exist before step 1
• Commit messages written as "update files" — write the actual message; vague messages make bisect and blame useless later

Checklist

• Every file path is specified from a known root (no bare filenames)
• Every code change is a complete, runnable code block (no ellipsis or TODO)
• Every destructive step has a verify command with expected output
• No step says "implement", "add", or "update" without full specifics
• Database migrations precede model/code changes
• Commit messages are written out verbatim
• Rollback instructions exist for irreversible steps
• Pre-conditions are listed and checkable before step 1
• A person who has never seen this codebase could execute the plan without asking questions