writing-plans

What this skill does

# Writing Plans

Create executable implementation plans that reduce ambiguity for whoever executes them. The skill walks Phase 1 → Phase 6 in a single turn for normal-sized plans; for unattended long runs, wrap in `/goal` (see below).

## For unattended multi-turn runs

Wrap the invocation in Claude Code's built-in `/goal` (v2.1.139+):

```
/goal "Claude has narrated a successful plan commit (with commit hash) and reported the Phase 4 reflection sub-agent verdicts inline" /superpowers:writing-plans <design-path>
```

`/goal` provides multi-turn continuation — a fresh fast model checks the condition against the conversation transcript after each turn and re-prompts until satisfied. **The evaluator does NOT read files or run commands** ([upstream docs](https://code.claude.com/docs/en/goal)) — phrase the condition as something Claude's own narration will demonstrate (commit-hash narration from `git-agent commit`, the literal Phase 4 reflection summary, an explicit completion statement). Conditions written against filesystem state (`_index.md exists`, `Execution Plan YAML present`, `git commit clean`) are unverifiable and will time out. For most reasonable-sized plans, `/goal` is unnecessary; the skill runs to completion in one turn.

## CRITICAL: Bail-Out Check (run first)

**Read `bdd-specs.md` from the resolved design folder. Count `Scenario:` occurrences. Bail out — do NOT decompose tasks — when EITHER:**

- BDD scenarios in `bdd-specs.md` < 3, **OR**
- Total estimated task count < 5 (use `2× BDD scenarios + 1 setup task` as a rough estimate; if the design `_index.md` carries an explicit "Task Estimate" hint, prefer that)

The OR-gate (was AND prior to v2.8.0) catches the common "2 BDD + many setup tasks" shape where the AND-gate previously let thin designs through into the full 6-phase pipeline.

**Bail-out response (output verbatim):**

> Design too thin for full task-decomposition pipeline (BDD < 3 OR estimated tasks < 5). Drafting a one-page lightweight plan inline instead. To force the full pipeline, re-invoke as `/superpowers:writing-plans --force <design-path>`.

Then write a single `_index.md` (no per-task files, no Phase 4 reflection, no plan evaluator) and exit. The `--force` token (literal in `$ARGUMENTS`, case-sensitive, matched as a whole token — not a substring of other words) bypasses this check.

## CRITICAL: Justification Check (run after bail-out)

**Read `_index.md` from the resolved design folder. Bail out — do NOT decompose tasks — when grep matches any of:**

```bash
grep -nE "STATUS:.*NOT.JUSTIFIED|DESIGN-NOT-YET-JUSTIFIED|DESIGN-CONSIDERED-DEFERRED|DO NOT IMPLEMENT" "<resolved-design-folder>/_index.md"
```

This catches designs the maintainer or a prior brainstorming sub-agent has explicitly marked as "not approved to advance" (see `docs/retros/checklists/design-v1.md` JUST-01 for full semantics, and `docs/retros/2026-05-09-v3-considered-deferred.md` for the inciting case). The marker is dispositive — do not interpret it away.

**On match, refuse deterministically (the marker is dispositive — do not interpret it away)**:

1. Output a one-line note explaining the matched line + path: `Refusing: <design-path>/_index.md:{N} is marked NOT-JUSTIFIED — '{matched text}'. Re-invoke /superpowers:brainstorming to revise the design, or pass --justify-override to bypass this gate.`
2. Exit without proceeding.

**Override**: Pass `--justify-override` (literal token in `$ARGUMENTS`, case-sensitive, whole-token match) to bypass this refusal. When the override token is present, continue to First Action.

**PROHIBITED**: Do NOT conflate `--force` (which bypasses the bail-out size gate above) with `--justify-override` (which bypasses this justification gate). They are independent failure modes and need independent overrides — a user passing `--force` for a thin design should still be refused if the design is also NOT-JUSTIFIED.

## First Action — Resolve Design Path

1. Resolve the design path:
   - If `$ARGUMENTS` provides a path (e.g., `docs/plans/YYYY-MM-DD-topic-design/`), use it
   - Otherwise, pick the `*-design/` folder whose basename sorts last under `YYYY-MM-DD-*-design/` — i.e., the highest date prefix in the name, not filesystem mtime. Use `ls -1d docs/plans/*-design/ 2>/dev/null | sort | tail -1` (do NOT use `ls -t` / `ls -1dt` — directory mtimes get bumped when an older folder's files are edited, which makes it rank above a freshly-created folder). Use the result directly; do NOT pause to confirm.
   - If no `*-design/` folder exists in `docs/plans/`, refuse with: `Refusing: no design folder found under docs/plans/. Run /superpowers:brainstorming first, or pass the design folder path explicitly.` Then exit.
2. Proceed to Initialization in the same turn.

## Initialization

1. **Design Check**: Verify the folder contains `_index.md` and `bdd-specs.md`.
2. **Context**: Read `bdd-specs.md` completely. This is the source of truth for your tasks.

## Background Knowledge

**Core Concept**: Explicit over implicit, granular tasks, verification-driven, context independence.

- **MANDATORY**: Tasks must be driven by BDD scenarios (Given/When/Then).
- **MANDATORY**: Test-First (Red-Green) workflow. Verification tasks must precede implementation tasks.
- **MANDATORY**: When plans include unit tests, require external dependency isolation with test doubles (DB/network/third-party APIs).
- **PROHIBITED**: Do not generate implementation bodies — no function logic, no algorithm code.
- **ALLOWED**: Interface signatures, type definitions, and function signatures that define the contract (e.g., `async function improve(params: ImproveParams): Promise<Result>`).
- **MANDATORY**: One task per file. Each task gets its own `.md` file.
- **MANDATORY**: _index.md contains overview and references to all task files.

## Phase 1: Plan Structure

Define goal, architecture, constraints, and context.

1. **Read Specs**: Read `bdd-specs.md` from the design folder (generated by `superpowers:brainstorming`).
2. **Draft Structure**: Use `./references/structure-template.md` to outline the plan.
3. **Write Context Section**: Populate the `## Context` section in `_index.md`:
   - State why this work is needed (motivation, constraints, prior incidents).
   - If modifying existing code, add a current-state vs target-state comparison table covering key dimensions (module structure, API shape, behavior, etc.). Omit the table for greenfield work.

## Phase 2: Task Decomposition

Break into small tasks mapped to specific BDD scenarios.

**PROHIBITED**: Do not ask the user to choose task granularity, approve decomposition, or confirm the plan mid-process. Apply the rules in steps 1-6 below plus these additions automatically; the Phase 4 sub-agent reflection is the quality gate and the post-commit `git show` diff is the user's audit surface. There is no in-skill approval step.

- Foundation tasks (setup, shared schema, types, config, storage) take lower `NNN` before feature pairs
- Bundle all scenarios of a Feature into one test file; split only when the Feature crosses independent service boundaries (e.g., frontend vs backend)

1. **Reference Scenarios**: **CRITICAL**: Every task must explicitly include the full BDD Scenario content in the task file using Gherkin syntax. For example:

   ```gherkin
   ## BDD Scenario

   Scenario: [concise scenario title]
     Given [context or precondition]
     When [action or event occurs]
     Then [expected outcome]
     And [additional conditions or outcomes]
   ```

   The scenario content should be self-contained in the task file, not just a reference to `bdd-specs.md`. This allows the executor to see the complete scenario without switching files.
2. **Define Verification**: **CRITICAL**: Verification steps must run the BDD specs (e.g., `npm test tests/login.spec.ts`).
3. **Enforce Ordering**: For each feature NNN, the test task (`task-NNN-<feature>-test`) must precede its paired impl task (`task-NNN-<feature>-impl`) via `depends-o