# writing-plans

> A Claude Code skill that produces task-by-task implementation plans with no placeholders — assumes zero codebase context, decomposes work into 2–5 minute TDD-first tasks, and ships a plan file ready for a fresh session to execute.

**Use case**: Turn a feature into an executable, no-handwaving implementation plan

**Canonical URL**: https://agentcookbooks.com/skills/writing-plans/

**Topics**: claude-code, skills, planning, documentation

**Trigger phrases**: "write a plan", "decompose this feature", "what's the implementation plan"

**Source**: [Jesse Vincent](https://github.com/obra/superpowers/tree/main/skills/writing-plans)

**License**: MIT

---

## What it does

`writing-plans` produces an implementation plan structured as a sequence of bite-sized tasks (2–5 minutes each), each with a failing test, the implementation steps, the verification command, and the commit message. Plans are written to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` and are designed to be handed off to a fresh session — meaning every plan assumes the executing agent has *zero* prior context on the codebase.

The "no placeholders" rule is the thing. Every task includes the actual code, the actual file paths, the actual commands. No "TBD", no "add error handling here", no "implement the rest". A plan with placeholders isn't a plan; it's a wishlist.

## When to use it

- Starting a feature that's bigger than one session
- Before kicking off `executing-plans` in a fresh session — they pair tightly
- When you want a record of intent before code, for review or async handoff
- Multi-step refactors where the order of operations matters
- Anything where you'd otherwise be tempted to "just start and see what happens"

When *not* to reach for it:

- One-task changes that finish in 10 minutes
- Pure investigations with no implementation outcome yet
- Spike work where the goal is learning, not shipping

## Install

From the [obra/superpowers](https://github.com/obra/superpowers) repo at `skills/writing-plans/`. Pairs directly with `executing-plans`, `subagent-driven-development`, and `using-git-worktrees`.

## What a session looks like

1. **Capture the architecture context** — tech stack, key files, conventions. The plan header records this so the executing session doesn't have to rediscover it.
2. **Map the file structure upfront** — what files will be touched, what's new vs. existing, what the responsibility of each is.
3. **Decompose into tasks**, each 2–5 minutes of focused work. A task includes:
   - Files affected
   - The failing test that defines done
   - Implementation steps in order
   - Verification command
   - Commit message
4. **Self-review the plan** before handoff — scan for placeholder words ("TBD", "TODO", "later", "add error handling"), check that types stay consistent across tasks, confirm the plan covers the spec.
5. **Save to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`** so the executing session has a stable path to load from.

The discipline that makes it work: the placeholder scan. The skill treats placeholder language as evidence the plan isn't done. If you wouldn't accept "TBD" in a code review, you don't accept it in a plan.

## Receipts

_TODO — to be filled in from a real planning session. Once a plan has been written and then executed by a separate session, this section will capture: how many tasks, how long the executing session ran without questions, how many placeholders the self-review caught, and where the plan and reality diverged._

## Source and attribution

From [Jesse Vincent's superpowers repository](https://github.com/obra/superpowers/tree/main/skills/writing-plans).

License: MIT.

The plan format is opinionated: every task has a failing test before implementation, and the plan-writer is required to include actual commands, not descriptions of commands. That rigidity is what lets `executing-plans` run a plan to completion in a fresh session without round-trips.