agent-skills/skills/writing-implementation-plans/SKILL.md

name, description, license, source

name	description	license	source
writing-implementation-plans	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.	MIT	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:

# <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:

### 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.