writing-plans · Implementation Plan Writing
Implementation plan writing: with a spec in hand and before touching code, write the plan. The reader is an engineer who has never seen this codebase or spec: the plan must state which files, interface signatures, exact spec values, and which test proves each task.
Tasks are cut into bite-sized units with independent test cycles; each step does one action with a checkable result (write failing test → run to confirm failure → minimal implementation → run to confirm pass → commit). Plans are saved to docs/superpowers/plans/. A self-review follows: spec coverage, step granularity, type consistency, Review Focus (five likely-to-bite inputs/failures the spec didn't name), and length proportion.
Example invocation: "Write an implementation plan — review before any code."
Full brief
Positioning
writing-plans authors implementation plans: spec exists, multi-step task, no code touched yet. Executing them belongs to executing-plans / subagent-driven-development.
Core capabilities
- Reader assumption: written for an engineer who has never seen the codebase or spec; they write idiomatic code, but can't know your decisions — files, interfaces, exact values, tests must be spelled out.
- File structure first: map created/modified files and responsibilities before defining tasks — decomposition decisions lock here.
- Task sizing: smallest unit with its own test cycle worth an independent review gate; each task yields independently testable deliverables.
- Step granularity: one action per step (write failing test / run to confirm failure / minimal implementation / run to confirm pass / commit); test steps carry test names, assertions, and spec-verbatim values.
- Interface contracts: each task declares Consumes / Produces (exact function names, parameter and return types) — neighbor tasks interface through them.
- Plan header: fixed header (goal/architecture/tech stack/spec path, Global Constraints copied verbatim from the spec, Review Focus — the five spec-implied input classes/failure modes most likely to bite a user).
- Self-review: spec coverage → step scan (non-deciding lines are gaps; bodies the signature+tests already determine are transcripts — fix both) → type consistency → Review Focus coverage → length proportion (a plan several times longer than the spec is wrong).
Workflow
- Scope check (split multi-subsystem specs into multiple plans)
- File structure (lock decomposition decisions)
- Task slicing (bite-sized, each with interface contracts)
- Write the plan (fixed header + tasks + steps)
- Self-review (five checks; fix inline)
- Save to
docs/superpowers/plans/YYYY-MM-DD-<feature>.md - Hand to the human for review + execution-method choice (subagent-driven / native)
Inputs & outputs
| Input | Notes |
|---|---|
| Spec / requirements doc | Required — for a multi-step task |
| Plan location preference | Optional — user preference overrides the default |
Output: implementation plan document (goal/architecture/constraints/Review Focus/tasks with steps).
Boundaries with adjacent skills
| Skill | Lane |
|---|---|
| writing-plans (this) | Writing implementation plans (before coding) |
| subagent-driven-development | Subagents executing the plan task-by-task |
| executing-plans | Native plan execution |
| brainstorming | Pre-plan brainstorming |
Fit
- Turning a spec into an executable implementation plan
- Design handoffs before cross-session/cross-person collaboration
- Letting an executor (human or agent) start without guessing
Before you start
- Have the spec/requirements ready.
- Plans are written before code; pick the execution method before starting.
writing-plans is part of the Aiglade Skill library. Invoke it from the Aiglade chat box in plain language.