writing-plans-enhanced

What this skill does

# Writing Plans (Enhanced)

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch, code to write, commands to run, and how to verify each step. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** This should be run in a dedicated worktree (created by brainstorming skill).

**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for plan location override this default)

## When to Use

```dot
digraph when_to_use {
    "Have spec or requirements?" [shape=diamond];
    "Single-step or exploratory?" [shape=diamond];
    "Covers multiple subsystems?" [shape=diamond];
    "writing-plans (this skill)" [shape=box];
    "Just implement directly" [shape=box];
    "Split into sub-plans first" [shape=box];
    "Use brainstorming skill first" [shape=box];

    "Have spec or requirements?" -> "Single-step or exploratory?" [label="yes"];
    "Have spec or requirements?" -> "Use brainstorming skill first" [label="no"];
    "Single-step or exploratory?" -> "Just implement directly" [label="yes"];
    "Single-step or exploratory?" -> "Covers multiple subsystems?" [label="no, multi-step"];
    "Covers multiple subsystems?" -> "Split into sub-plans first" [label="yes"];
    "Covers multiple subsystems?" -> "writing-plans (this skill)" [label="no, single subsystem"];
}
```

## The Process

Write plans in five phases. Each phase has outputs the next phase depends on.

1. **Pre-Writing — Gather Context:** read spec, study codebase, identify patterns.
2. **Scope Check:** verify this is a single subsystem sized right for one plan.
3. **File Structure:** map files to create/modify before decomposing tasks.
4. **Task Decomposition:** bite-sized TDD steps (and non-TDD variants where appropriate).
5. **Self-Review:** check against spec, scan for placeholders, verify type consistency.

## Phase 1: Pre-Writing — Gather Context

**Don't skip this.** A plan written without context produces tasks that conflict with the codebase and force the implementer to guess.

**Read the spec twice.** The first read builds intuition. The second catches the details you glossed over. Note every explicit requirement and every implicit assumption.

**Study the codebase** before decomposing tasks:
- What conventions does the codebase follow? (naming, directory layout, test framework, lint rules)
- Where do similar features live? Read one complete example end-to-end.
- What are the extension points? (interfaces, base classes, plugin registries)
- How is this tech stack wired up? (dependency injection, config loading, build/test commands)

**Identify risks and unknowns:**
- Which tasks touch code you don't fully understand?
- Are there external dependencies (APIs, services, libraries) whose behavior you'd need to verify?
- Where could a naïve implementation break existing tests?

Capture findings briefly at the top of the plan under **Context** (codebase conventions, reference patterns, known risks). The implementer reads this before touching code.

## Phase 2: Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

**Plan size guidance:**

| Task count | Shape | Notes |
|------------|-------|-------|
| 3–10 | Single plan | Normal size — keep tasks in one file |
| 11–20 | Single plan with phases | Group tasks under `## Phase N:` headings |
| 20+ | Split into multiple plans | One per phase or subsystem; link them |

If the plan keeps growing past 20 tasks, stop and ask: is this actually multiple features? Split before writing tasks you don't need yet (YAGNI).

## Phase 3: File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure — but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

## Phase 4: Task Decomposition

### Bite-Sized Step Granularity

**Each step is one action (2–5 minutes):**
- "Write the failing test" — step
- "Run it to make sure it fails" — step
- "Implement the minimal code to make the test pass" — step
- "Run the tests and make sure they pass" — step
- "Commit" — step

### Task Metadata

Every task should carry metadata that tells the implementer (or a subagent) how to execute it:

```markdown
### Task N: [Component Name]

**Type:** TDD | Config | Refactor | Migration | Documentation | Infrastructure
**Depends on:** Task M (or: none)
**Parallel-safe:** yes | no
**Risk:** low | medium | high — [one-line reason if medium/high]
```

- **Depends on:** lets the executor order tasks correctly. Use `none` liberally — tasks that don't depend on prior work can run in parallel.
- **Parallel-safe:** if two tasks don't touch the same files or shared state, mark both as parallel-safe. Subagent-driven execution uses this to fan out.
- **Risk:** high-risk tasks (schema migrations, auth changes, file deletions) warrant extra verification steps and explicit rollback notes.

### Non-TDD Task Patterns

Not every task fits the red–green–commit loop. For non-code tasks, substitute a verification style that proves the task succeeded. See `./task-templates.md` for full templates.

| Task type | Verification instead of test |
|-----------|------------------------------|
| Config change | Load config, print resolved value, assert expected |
| File move/rename | `git status` shows the rename; imports still resolve; tests still pass |
| Documentation | Cross-links resolve; code blocks parse; examples runnable |
| Infrastructure / IaC | `terraform plan` / `kubectl diff` shows expected delta; dry-run |
| Refactor (no behavior change) | All pre-existing tests still pass; no new tests needed |
| Migration (data/schema) | Dry-run succeeds; rollback plan present; applied on copy first |

For any non-TDD task, state the verification command and expected output explicitly.

## Plan Document Header

**Every plan MUST start with this header:**

```markdown
# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Context:**
- Codebase conventions: [one line]
- Reference pattern: [file path to similar feature]
- Known risks: [one line or "none"]

---
```

## Task Structure

### Standard TDD Task

````markdown
### Task N: [Component Name]

**Type:** TDD
**Depends on:** none
**Parallel-safe:** yes
**Risk:** low

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `t