Writing Plans

---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---

# Writing Plans

Write an implementation plan for an engineer with zero context for this codebase and questionable test taste. Decompose into bite-sized, independently verifiable tasks. DRY, YAGNI, TDD, frequent commits.

Pairs with `/generate-prp` (research-driven blueprint) and `/writing-plans`. Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md` (user preference overrides). Worktree, if isolated, comes from `using-git-worktrees` at execution time.

Announce: "Using the writing-plans skill to create the implementation plan."

## Scope

- One plan per independent subsystem — each must produce working, testable software alone. If the spec spans several, suggest splitting into separate plans.

## File structure (decide before tasks)

- Map every file to create/modify and its single responsibility — this locks in decomposition.
- One responsibility per file; prefer small focused files; files that change together live together (split by responsibility, not layer).
- Follow established codebase patterns. Restructure a file only when it's grown unwieldy AND you're already modifying it.

## Task right-sizing

- A task = the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate.
- Fold setup/config/scaffolding/docs into the task whose deliverable needs them. Split only where a reviewer could reject one task while approving its neighbor.
- Each task ends with an independently testable deliverable.

## Step granularity

Each step is one 2-5 min action: write failing test → run it (confirm RED) → minimal implementation → run (confirm GREEN) → commit.

## Plan document shape

Header (required):

```markdown
# [Feature] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. Steps use `- [ ]` checkboxes.

**Goal:** [one sentence]   **Architecture:** [2-3 sentences]   **Tech Stack:** [key libs]

## Global Constraints
[Project-wide spec requirements — version floors, dep limits, naming/copy rules,
platform — one line each, exact values verbatim. Every task implicitly includes this.]
```

Per task:

- **Files** — exact `Create:` / `Modify:path:lines` / `Test:` paths.
- **Interfaces** — `Consumes:` exact signatures from earlier tasks; `Produces:` exact names + param/return types later tasks rely on (implementers see only their own task).
- **Steps** — checkbox per step, with the ACTUAL test code, exact run command + expected output, the ACTUAL implementation code, and the commit.

## No placeholders (these are plan failures)

- "TBD"/"TODO"/"implement later"/"fill in details".
- "Add appropriate error handling / validation / edge cases".
- "Write tests for the above" without the test code; "similar to Task N" without repeating the code (tasks may be read out of order).
- Steps describing what without showing how (code steps need code blocks).
- References to types/functions/methods not defined in any task.

## Self-review (yourself, not a subagent)

1. **Spec coverage** — every spec requirement maps to a task; list + fill gaps.
2. **Placeholder scan** — hunt the patterns above; fix inline.
3. **Type consistency** — names/signatures in later tasks match earlier definitions (`clearLayers()` in T3 vs `clearFullLayers()` in T7 is a bug).

For a fresh-eyes pass, dispatch `plan-document-reviewer-prompt.md`.

## Execution handoff

Offer: **(1) Subagent-driven** (recommended) — `superpowers:subagent-driven-development`, fresh subagent per task + two-stage review; **(2) Inline** — `superpowers:executing-plans`, batch execution with checkpoints.

<!-- budget: ~74 -->