Why Does Superpowers Insist on Ultra‑Detailed Writing‑Plans?

Why a spec can’t go straight to implementation

Even after brainstorming clarifies requirements and a spec is written, the execution gap remains because the interpretation rights belong to the implementer. Human engineers mentally fill in many details—task ordering, test placement, file boundaries—while an agent would interpret the spec inconsistently.

What the writing-plans skill actually does

It is not a traditional project schedule; it is an "executable script" for the agent. The plan must enumerate concrete actions such as which files to modify, which failing test to write first, the expected failure output, the minimal implementation, the verification command, and the final commit.

Which files are affected

Which failing test to write first

What the failure should look like

The minimal implementation

The command that confirms success

What to commit after the step

This level of detail prevents the agent from filling ambiguous spaces with its own assumptions, which often leads to divergent implementations.

Why agents fear ambiguity

Agents thrive on clear, narrow instructions. When a plan leaves room for interpretation, the agent may inject its own architecture choices, file organization, extra features, or loosely defined tests, resulting in code that looks complete but deviates from the original design intent.

How writing-plans eliminates design‑to‑implementation distortion

Typical refactoring problems stem from a loss of fidelity between spec and code. By forcing the engineer to decide file structure, test order, and verification steps up front, the plan acts as a "pre‑emptive guard" against drift.

Step 1: Lock the file structure

Before defining tasks, enumerate the files to be created or modified, clarifying responsibilities, grouping, and boundaries.

Step 2: Split work into 2‑5‑minute actions

Each task is small enough that the agent cannot embed a whole new interpretation, reducing the risk of deviation.

Step 3: Embed verification in every step

Instead of a final validation, each step includes the exact command to run and the expected output, ensuring the agent knows when it has succeeded before proceeding.

Why the plan is tied to TDD

The skill strongly prefers Test‑Driven Development granularity. If a plan omits the RED‑GREEN‑REFactor cycle, the agent will likely implement first and add tests later, re‑introducing ambiguity. By baking TDD into the plan, the execution phase is forced to follow a disciplined, test‑first flow.

What a good plan looks like

Independent tasks : split by verifiable outcome, not by module or layer.

Concrete steps : no vague phrases like “add necessary error handling”; each step must specify exact code, command, and expected result.

Verifiable actions : every step includes precise commands and expected outputs, eliminating “TODO” or “later” placeholders.

Common misunderstandings

1. Abstract plans are “higher level”

Human‑centric plans can afford ambiguity; agent‑centric plans cannot. The more a plan can be executed directly, the more valuable it is.

2. Detailed plans slow you down

Short‑term overhead is offset by eliminating costly rework, rollbacks, and mis‑aligned implementations.

3. A spec alone is enough

A spec explains *what* and *why*; a plan explains *how* step‑by‑step. Both are required and not interchangeable.

How the plan integrates with execution skills

After the plan is written, Superpowers hands it to either subagent-driven-development or executing-plans. Both require the plan to be sufficiently concrete; otherwise the execution phase simply hands interpretation back to the agent.

In summary, writing-plans turns the hidden expertise of senior engineers into an explicit, test‑first, verifiable execution script, ensuring that agents implement designs without drifting.