⚡
★ 86.6k

Writing Plans

Core Principle: Each task must be small enough that an engineer without context can complete it in 2–5 minutes.

Why Plans Matter

A plan is the contract between what was designed and what gets built. Without a plan, execution is improvised — and improvised AI-assisted development produces inconsistent, unreviewed, and often incorrect results.

More importantly, a written plan creates an audit trail. When something goes wrong (and in software development, something always eventually goes wrong), a plan tells you what was intended. It lets you distinguish between "the AI deviated from the plan" and "the plan itself was flawed." That distinction matters for debugging, for post-mortems, and for getting better over time.

In Superpowers, plans are written after the brainstorming phase and before any code is written. The plan is the bridge.

The Core Principle in Detail

Each task must be small enough that an engineer without context can complete it in 2–5 minutes.

This rule sounds simple but has profound implications.

"Without context" means: if you handed the task description to someone who has never seen this codebase before, they would know exactly what to do. The task is self-contained. All the information needed to complete it is in the task description itself — the exact file, the exact code, the exact command.

"2–5 minutes" is a forcing function. If completing a task takes longer than that, it's too big. Break it down. Tasks that take 30 minutes contain multiple sub-decisions and multiple failure points. When something goes wrong, you don't know which part failed. Small tasks fail fast, fail clearly, and fail cheaply.

Plan Document Header Format

Every plan document begins with a standardized header:

# Implementation Plan: [Feature Name]

**Date:** [YYYY-MM-DD]
**Branch:** [git branch name]
**Author:** [AI agent or human]
**Status:** PENDING | IN_PROGRESS | COMPLETE
**Spec Reference:** [Link to or summary of approved brainstorm spec]

## Context
[1–3 sentences: What is this plan implementing and why?]

## Scope
**In scope:**
- [What will be built]

**Out of scope:**
- [What will NOT be built — explicitly]

## Dependencies
- [Any prerequisites that must exist before this plan starts]

The header creates a common anchor point for everyone reviewing the plan. The "Out of scope" section is especially important — it prevents scope creep from sneaking in during execution.

Task Structure

Each task in the plan follows this format:

### Task [N]: [Task Title]

**Status:** PENDING
**Estimated time:** 2–5 minutes
**File(s):** `src/path/to/file.ts`

**What to do:**
[One paragraph describing the change in plain language]

**Exact code:**
```typescript
// The complete, copy-pasteable code for this change
// No placeholders. No "fill this in". Complete code only.
export function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Exact command (if applicable):

npm run test -- --testPathPattern=calculateTotal

Verification: [How to know this task succeeded]

Rollback: [How to undo this task if something goes wrong]


The key word in that structure is **exact**. Not approximate. Not "something like this." Exact file paths, exact code, exact commands. If the task requires decisions to be made during execution, the task is too vague. Move those decisions back to the planning phase.

---

## DRY in Planning

**Don't Repeat Yourself** applies to plans as much as it applies to code.

If multiple tasks use the same utility function, the plan should note that this utility was created in Task 3 and subsequent tasks depend on it. Don't copy-paste the utility definition into every task that uses it.

If multiple tasks follow the same pattern (e.g., "add a new API route"), note the pattern once and reference it: "This task follows the route pattern established in Task 2."

DRY plans are shorter, easier to review, and less likely to have inconsistencies between tasks.

---

## YAGNI in Planning

**You Aren't Gonna Need It** means the plan only covers what was approved in the brainstorm spec.

Common YAGNI violations in plans:
- Adding error handling for cases not mentioned in the spec
- Creating abstractions "for future use"
- Adding logging infrastructure beyond what's required
- Building configuration systems for settings that have exactly one value today

Every addition to a plan must be traceable to the approved spec. If you can't point to the spec requirement that justifies a task, the task shouldn't be in the plan.

---

## TDD in Planning

Test-Driven Development must be baked into the plan structure. The convention is: **every feature task is preceded by a test task**.

```markdown
### Task 4: Write failing test for order total calculation
**File:** `src/services/__tests__/order.test.ts`
[Write the test that will fail until Task 5 is complete]

### Task 5: Implement order total calculation
**File:** `src/services/order.ts`
[Write the code that makes Task 4's test pass]

This pairing is not optional. If you see a plan where implementation tasks appear without corresponding test tasks immediately preceding them, the plan is incomplete. Send it back.

Scope Management

Plans should be reviewed for scope before execution begins. Use this checklist:

Scope creep signals:

  • Tasks that weren't discussed in brainstorming
  • Tasks labeled "while we're at it"
  • Tasks that touch files unrelated to the approved spec
  • The number of tasks is more than 2x what was expected

Scope reduction signals:

  • Tasks that duplicate existing functionality
  • Tasks that are "nice to have" rather than required
  • Tasks that can be deferred to a follow-up plan

If scope creep is detected, stop. Do not begin execution. Return to the brainstorming phase and get the new scope approved before updating the plan.

The Review Process

Before execution begins, the plan goes through a structured review:

Review Stage 1: Completeness

  • Does every task have a clear description, exact code, and exact file path?
  • Is there a test task for every implementation task?
  • Are dependencies between tasks clearly noted?
  • Is the rollback path clear for each task?

Review Stage 2: Scope Alignment

  • Does every task trace back to the approved spec?
  • Are out-of-scope items explicitly excluded?
  • Is anything missing that the spec requires?

Review Stage 3: Task Size

  • Can every task be completed in 2–5 minutes?
  • Are there any tasks that make multiple different changes?
  • Are any tasks vague enough that the executor would need to make design decisions?

Approval

The plan requires explicit approval before execution begins. Like the brainstorming gate, the planning gate is hard: no execution without an approved plan.

Example: A Well-Structured Plan

# Implementation Plan: User Email Notification on Order Ship

**Date:** 2025-03-15
**Branch:** feature/order-ship-email
**Status:** PENDING
**Spec Reference:** Brainstorm approved 2025-03-14 — send transactional email
                    when order status changes to "shipped"

## Scope
**In scope:** Trigger email on status change, basic email template, test coverage
**Out of scope:** Email preferences, unsubscribe flow, HTML templates (plain text only)

---

### Task 1: Write failing test for email trigger
**File:** `src/services/__tests__/order.service.test.ts`
**Code:** [test that expects sendEmail to be called when status = "shipped"]

### Task 2: Implement email trigger in OrderService
**File:** `src/services/order.service.ts`
**Code:** [call emailService.send() in updateStatus() when newStatus === "shipped"]

### Task 3: Write failing test for email template
**File:** `src/email/__tests__/order-shipped.template.test.ts`
**Code:** [test that template output contains order ID and tracking number]

### Task 4: Implement email template
**File:** `src/email/order-shipped.template.ts`
**Code:** [plain text template with order ID and tracking number interpolation]

This plan is small (4 tasks), traceable to spec, test-first, and each task is completable in under 5 minutes.

A good plan is boring. If reading the plan is exciting because of all the clever things it's going to build, that's a red flag. Good plans are thorough, precise, and unambiguous — the interesting decisions were made in brainstorming.