writing-plans

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Context: If working in an isolated worktree, it should have been created via the superpowers:using-git-worktrees skill at execution time.

Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• (User preferences for plan location override this default)

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

Lightweight Plans (Small Changes)

For small changes — a few files, a single feature, no cross-subsystem coordination — the full plan format below is overkill. Write a lightweight plan instead:

# [Feature] Plan

**Goal:** one sentence

**Files:**
- `src/foo.py` — change `bar()`
- `tests/test_foo.py` — add test

**Steps:**
1. Add a failing test for the new behavior
2. Implement it
3. Run `pytest tests/test_foo.py -v` and confirm green
4. Commit

Binding rules in lightweight mode (same as full):

• No placeholders — every step must be concrete, no "TBD"/"implement later"
• Test first — write the failing test before the implementation
• One self-review pass — does each step have a testable outcome?

Use the full format below when the change spans multiple files with interfaces between them, needs global constraints, or the implementer lacks context. When in doubt, lightweight.