The writing-plans skill, reviewed

What it tells the agent to do

1. Announce the skill and check scope. Suggest one plan per subsystem if the spec spans several.
2. Map which files will be created or modified and what each is responsible for.
3. Start the plan with the required header: goal, architecture, stack, spec path, global constraints, review focus.
4. Write right-sized tasks with exact files and interfaces, each as failing test, run, implement, run, commit.
5. Self-review for spec coverage, vague or bloated steps, type consistency, review focus and length. Fix inline.
6. Save to docs/superpowers/plans/, ask the human to review it and to choose subagent-driven or native execution.
7. Hand off to subagent-driven-development or executing-plans to match their choice.

Lines worth reading

Straight from the file, with why each one matters.

1. line 3Use when you have a spec or requirements for a multi-step task, before touching code

   Says when to use it, but never says that it writes a plan. The name has to carry that.

2. line 143That is the whole requirement: unambiguous, not complete.

   The core rule. Pin down the decisions, leave the bodies to the implementer. It keeps plans from becoming code dumps.

3. line 171A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.

   A concrete example of the naming drift that bites long multi-task plans. Easy to check, often missed.

4. line 192Runs well with a mid-tier session model, since the plan carries the design.

   Frank about cost: spend the smart model on planning and review, run a cheaper one for the typing.

5. line 14it should have been created via the `superpowers:using-git-worktrees` skill at execution time.

   An odd line for a planning step. It points to a worktree made at execution time, which comes after planning.

Watch out for

Nothing risky that Kin could see in SKILL.md. Scripts beside it were not read.

The scorecard

• TriggerSays when to use it
  6/10

  Clear 'when', but the description never says it writes an implementation plan.

• FocusOne clear job
  9/10

  One job: turn a spec into an executable plan.

• LeanLight to load
  8/10

  About 200 lines, mostly directive. Some explaining could be trimmed.

• ConcreteSteps you can follow
  9/10

  Full header and task templates, step rules, a five-point self-review.

• SafeSafe to run
  9/10

  Writes a doc and waits for human review. Commits are only in the plan for later.

How it could be better

1. Say what it does in the description

   The agent sees only the description. Leading with the output makes it easier to match requests like 'plan this feature'.

   Add

   description: Writes a step-by-step TDD implementation plan (files, interfaces, tests, commits) from a spec or requirements. Use when you have a spec for a multi-step task, before touching code.

   Copy

2. Add a fallback when sibling skills are missing

   The header and handoff require superpowers sub-skills that may not be installed alone.

   Add

   If superpowers:subagent-driven-development or superpowers:executing-plans is not available, tell the user and execute the plan task by task in this session, checking off each step.

   Copy

3. Make the test commands language-neutral

   The template hardcodes pytest. Plans for other stacks may copy it by mistake.

   Add

   Use the project's own test runner in every Run step (e.g. `<test command> <test file>::<test name>`), not pytest unless the project uses it.

   Copy

4. Clarify the worktree line

   It mentions execution time inside a planning skill, which leaves unclear what the planner should do now.

   Add

   **Context:** Planning does not need a worktree. If the user wants isolated execution, note in the plan that it should run in a worktree made with superpowers:using-git-worktrees.

   Copy