writing-plans

Files (2)

• SKILL.md
• plan-document-reviewer-prompt.md

SKILL.md (first lines)

# Writing Durable Plans

## Purpose

A plan is a durable execution contract for work that spans multiple rounds,
context compaction, or handoff between the main agent and workers. It preserves
what a future implementer cannot safely reconstruct from a task title alone:

- user intent and the real product, business, or operational behavior;
- architecture and module relationships;
- exact constraints, interfaces, values, compatibility boundaries, and files;
- necessary technical and code details;
- dependency and construction order;
- semantic acceptance scenarios, evidence, and readback;
- repository-operation preferences; and
- recovery state needed to resume after interruption.

Assume the implementer is capable but starts with no conversation context. Give
them enough specific information to construct and verify the intended result,
not a generic principles document or a micro-step transcript.

## Ground the contract

1. Read the applicable request, stable specifications, repository instructions,
   relevant implementation, tests, and current repository state.
2. Record stable requirements by reference rather than copying entire specs.
   Repeat only the exact values, interfaces, compatibility rules, decisions, or
   code detail that the worker needs at the point of construction.
3. Map the architecture: which modules own which behavior, how data or control
   crosses their boundaries, and why the construction order follows from those
   relationships.
4. Inspect current context for commit, push, branch, and worktree preferences.
   When a preference is absent and changes execution, ask once; never push
   without clear authority.

## Preserve decisions and open boundaries

A negative compatibility boundary is not a positive architecture decision. For
example, a rule that an unapproved remote sink must not be introduced does not
approve a local file, in-memory store, injected sink, or any other substitute.

When storage, sink, failure strategy, source layout, ownership, or another
construction choice lacks evidence, record it as an open decision or blocker.
State what evidence or approval resolves it and keep dependent work conditional.
A fresh worker must not treat an inference as an approved decision merely because
the plan names a compatibility boundary.

Save plans to `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md` unless the
project or user specifies another durable location.

## Task boundaries

Organize tasks around independently meaningful, testable deliverables. A task
may include setup, implementation, tests, documentation, and review when they
form one product or operational outcome. Split when a later task depends on a
distinct accepted behavior, not to force every action into a short time box.

Use red-green testing when it discriminates the behavior being changed.
Compilation, linting, and unit tests are support signals, not the complete
acceptance claim. Every task must derive semantic acceptance from its real
product, business, or operational scenario:

- frontend work verifies the rendered visual state and the relevant interaction;
- persistence work verifies save, restart or reload, and readback;
- API, CLI, and automation work exercises meaningful arguments, failure paths,
  and the resulting state; and
- migrations or compatibility work verifies the promised boundary against a
  representative existing consumer or artifact.

Routine code that a competent worker can infer does not belong in the plan. Do
include code snippets, signatures, schemas, commands, or exact values where an
incorrect inference would change behavior, compatibility, construction order,
or acceptance evidence.

## Plan document header

Every durable plan begins with:

```markdown
# [Feature Name] Implementation Plan

**Goal:** [User-visible or operational outcome.]

**Stable references:** [Specs, decisions, instructions, and repository state
that the plan relies on.]

**Repository operations:** [Known commit/push/branch/worktree preference, or
the one decision still requiring user input.]

**Recovery state:** [What a worker should read first after context compaction,
which completed deliverables are trusted, and which evidence remains to gather.]
```

## Task template

Use this structure for each deliverable. Fill every field with task-specific
information; omit only fields that truly do not apply and explain why.

````markdown
### Task N: [Meaningful deliverable]

**Project meaning:** Why this task exists in the product or operation, including
the user-visible or operational problem it resolves.

**Architecture relationship:** Which modules, ownership boundaries, or data and
control flows this changes, and how it fits the surrounding system.

**Technical contract:**
- Files: Create/modify/delete exact paths.
- Interfaces and values: exact signatures, schemas, names, configuration
  values, compatibility conditions, and error behavior.
- Constraints: stable references plus the task-specific detail that must not be
  inferred differently.

**Dependencies:** What must already be accepted, what this task unblocks, and
the required construction order.

**Implementation notes:** The non-routine technical decisions, code excerpts,
commands, or data shapes needed to construct this deliverable correctly. Link

From BB-84C/superpowers-lite, MIT.

More from BB-84C/superpowers-lite