---
name: writing-implementation-plans
description: Use when requirements are settled and a multi-step change needs an implementation plan that memoryless delegates can execute without access to the originating conversation.
license: MIT
source: https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md
---

# Writing Implementation Plans

A plan is an executable handoff, not a summary of intent. The worker may be a
fresh CLI delegate with no conversation history, and individual tasks may be
assigned out of order. If the plan leaves a choice implicit, the worker will
have to invent it.

## Before writing tasks

1. Read the settled spec or requirements and inspect the actual code paths,
   tests, project instructions, and established patterns involved.
2. Resolve contradictions and material unknowns before planning. Marking them
   `TBD` only moves the design decision to a less-informed delegate.
3. Map every file to create or modify and give each one a clear
   responsibility. Avoid unrelated restructuring.
4. Split work into independently testable vertical slices. Fold setup,
   migrations, wiring, and documentation into the slice that needs them;
   don't create standalone tasks that leave the system unusable.
5. Identify shared files and state. Tasks that edit the same bootstrap file,
   schema, migration sequence, or live environment are sequential unless the
   design removes that collision. See `parallel-delegate-shared-files`.

## Plan header

Start with:

```markdown
# <Feature> Implementation Plan

**Goal:** <one sentence>

**Architecture:** <two or three sentences describing the approach and boundaries>

**Stack and environment:** <relevant runtimes, services, jail/container, database>

## Global constraints

- <exact version, naming, compatibility, security, tenant-isolation, and scope rules>

## Verification

- <commands for targeted tests, full regression tests, and any real end-to-end check>
```

Copy exact values from the requirements. For multi-tenant work, state the
tenant/RLS invariants explicitly; never let a worker infer them from nearby
code. For remote or production-adjacent work, state the exact host/jail,
whether mutation is authorised, and how secrets must be read without being
printed.

## Task contract

Each task must stand alone:

```markdown
### Task N: <independently testable outcome>

**Depends on:** <prior task outputs, or "none">

**Files:**
- Create: `exact/path`
- Modify: `exact/path` — <symbol or section>
- Test: `exact/path`

**Interfaces:**
- Consumes: <exact names, signatures, schemas, or artifacts>
- Produces: <exact names, signatures, schemas, or artifacts>

**Requirements:**
- <observable behavior and edge cases>

**Steps:**
- [ ] Write the failing test for <behavior>.
- [ ] Run `<targeted command>`; expect <specific failure proving the test is red-capable>.
- [ ] Implement the smallest change that passes it.
- [ ] Run `<targeted command>`; expect <specific success>.
- [ ] Run `<broader command>`; expect no regressions.
- [ ] Commit only this task's files with `<message or project convention>`.

**Report:** <facts and evidence the delegate must return>
```

Write exact commands and concrete expected signals. Include code or
pseudocode only where it removes a real ambiguity; don't turn the plan into a
second implementation. When a task brief will be extracted from the plan,
repeat its binding constraints instead of saying “same as above.”

## Self-review before delegation

- Trace every requirement to a task and every task to the goal. Remove gaps
  and scope creep.
- Search for placeholders and vague steps: `TBD`, `TODO`, “handle errors,”
  “add validation,” “write tests,” “similar to Task N.” Replace each with an
  explicit decision or action.
- Check that interface names and types match across tasks.
- Check ordering: a task must not consume an artifact that does not exist yet.
- Check concurrency: no parallel tasks may edit the same file or mutate the
  same shared environment.
- Check verification: every claimed outcome has a command or observation that
  could prove it false.
- Have the user approve material architectural or scope decisions before
  implementation begins.

When dispatching tasks, still apply `delegate-brief-writing`: the extracted
task plus relevant global constraints, confirmed facts, credentials handling,
verification, and report contract form the self-contained brief.