writing-plans

Overview

What the writing-plans skill does

The writing-plans skill helps you turn a product spec or technical requirements document into a complete, implementation-ready plan before anyone touches code. It is designed for situations where you have a multi-step feature or change to ship, and you want a clear, decomposed plan another engineer can follow without prior context.

Using writing-plans, you generate a plan that:

• Assumes the implementer is a capable developer but new to your codebase and domain.
• Spells out which files to create or modify for each part of the work.
• Calls out required tests, documentation updates, and manual checks.
• Breaks the work into bite-sized, shippable tasks with clear boundaries.

This makes it easier to hand off work, review the plan, and avoid scope creep or hidden edge cases. It reflects practices like DRY, YAGNI, TDD, and frequent commits, but focuses on project planning and task decomposition, not code generation.

Who is writing-plans for?

Use the writing-plans skill if you are:

• Tech leads and engineering managers who need repeatable planning for features and refactors.
• Individual developers who want to clarify their own approach before implementing risky or cross-cutting changes.
• Teams using subagents or distributed work that require clear written plans to coordinate contributors.

It is a strong fit when:

• You have a spec or requirements for a feature, migration, or integration.
• The work touches multiple files, components, or services.
• You want someone else to be able to implement the work without asking you constant questions.

It is not a great fit when:

• You are still brainstorming the problem or solution (use an ideation/brainstorming skill first).
• The task is tiny (e.g., a single-line fix) and does not need a formal plan.
• You are primarily looking for code review or code generation, not planning.

How it fits into your workflow

The repository expects writing-plans to be used after a brainstorming phase and in a dedicated worktree for the project. The usual flow is:

1. Brainstorm and clarify the spec (outside this skill).
2. Create or open a dedicated worktree for the feature.
3. Run the writing-plans skill to produce the implementation plan.
4. Save the plan (by default) to:
   • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
   • or a user-preferred plan location you define.
5. Optionally dispatch a plan document reviewer subagent using the provided template to validate the plan before implementation.

How to Use

Installation and setup

1. Install the writing-plans skill

You can install the skill directly from the obra/superpowers repository:

npx skills add https://github.com/obra/superpowers --skill writing-plans

This pulls in the writing-plans skill definition and its supporting prompts so you can use it in your own projects.

2. Inspect the core files

After installation, review these key files to understand and adapt the workflow:

• skills/writing-plans/SKILL.md – Main description of how the skill should behave, including scope, plan structure, and assumptions about the engineer.
• skills/writing-plans/plan-document-reviewer-prompt.md – A reusable prompt template for a subagent that reviews your finished plan.

Your local paths may differ depending on where you vendor or mirror the repository, but the filenames are the same.

Preparing to run writing-plans

3. Confirm your spec and scope

Before using writing-plans, make sure you have:

• A clear spec or requirements document for the feature or change.
• Enough detail to identify the main components, integrations, and constraints.

The skill includes a Scope Check step: if your spec covers multiple independent subsystems, it expects that work to have been split into separate sub-project specs during brainstorming. If that did not happen, you should:

• Break the work into separate plans, one per subsystem.
• Ensure each plan can produce working, testable software on its own.

This prevents a single plan from becoming unmanageable and helps align work with deployable units.

4. Prepare a worktree and plan file

The upstream guidance assumes you:

• Work in a dedicated worktree for the feature (set up during brainstorming).

• Save the resulting implementation plan as:

  • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

You can override this location if your team prefers a different directory structure, such as docs/plans/ or planning/. The important part is that the plan is checked into version control, versioned with the code, and easy to find later.

Running the skill and writing a plan

5. Announce and start the planning session

When you invoke the skill or start your planning conversation, the guidance is to explicitly state:

"I'm using the writing-plans skill to create the implementation plan."

This clarifies that the goal is a structured implementation plan, not design exploration or code output.

6. Map the file structure first

Before listing tasks, writing-plans emphasizes file-level decomposition:

• Identify which files will be created or modified.
• Assign each file a single, clear responsibility.
• Design units with well-defined interfaces and boundaries.

At this stage, the plan should answer:

• Where does new logic live?
• Which existing files are touched, and why?
• How do these files interact at a high level?

Locking in a sensible file structure early makes task decomposition, reviews, and future refactors much easier.

7. Break work into bite-sized tasks

Once the file map is in place, use writing-plans to turn the spec into a sequence of bite-sized, independently understandable tasks. The upstream guidance stresses:

• Each task should have a clear objective and be actionable.
• Tasks should be small enough to allow frequent commits.
• The plan should be DRY (no redundant instructions) and avoid YAGNI work (no speculative tasks).

For each task, the plan should include:

• Which files it touches.
• What code or configuration needs to change at a high level.
• What tests to add or update.
• Any documentation that must be updated.

The goal is that an engineer with minimal context can pick up any single task and complete it with confidence.

8. Plan for testing and documentation

writing-plans expects you to embed testing and documentation directly into the plan:

• Identify unit tests, integration tests, or end-to-end tests that need to be added or updated.
• Call out how to run tests (e.g., commands, test entry points) where relevant.
• Specify required documentation updates, such as README sections, user guides, or API docs.

This ensures quality and maintainability are first-class parts of the plan, not afterthoughts.

Reviewing and iterating on the plan

9. Use the plan document reviewer template (optional but recommended)

The plan-document-reviewer-prompt.md file provides a structured prompt for a plan document reviewer subagent. Its purpose is to:

• Check that the plan is complete and matches the spec.
• Validate that task decomposition is realistic and actionable.
• Confirm that an engineer could implement the plan without getting stuck.

The template lists categories for the reviewer to check, including:

• Completeness – No TODOs, placeholders, or missing steps for important requirements.
• Spec Alignment – The plan covers the spec without major scope creep.
• Task Decomposition – Tasks have clear boundaries and are implementable.
• Buildability – A competent engineer can follow the plan end-to-end.

The reviewer is instructed to focus on issues that would cause real implementation problems, not minor wording or stylistic preferences.

You can integrate this reviewer step into your CI, review workflows, or manual review process.

10. Iterate based on feedback

If the reviewer (human or subagent) finds issues such as missing requirements, contradictory steps, or overly vague tasks:

• Update the plan file with corrections.
• Re-run or re-dispatch the reviewer if needed.
• Once the plan is approved, treat it as the source of truth for implementation.

Adapting writing-plans to your team

11. Customize structure and conventions

While the upstream skill defines clear behaviors and defaults, you can adapt it by:

• Changing the plan file location to match your repository layout.
• Adding team-specific checklists (e.g., security review, performance testing) as recurring tasks.
• Integrating the plan with your issue tracker by mapping tasks to tickets.

Because writing-plans is primarily about structured workflow and project management, it translates well across languages, frameworks, and domains.

FAQ

When should I use the writing-plans skill?

Use writing-plans whenever you have a multi-step feature, refactor, or integration and a reasonably clear spec, and you want a written implementation plan that another engineer can execute without context. It is especially useful before complex changes that touch multiple files or subsystems.

When is writing-plans not a good fit?

writing-plans is not ideal when:

• You are still exploring solutions and the spec is unstable.
• The work is so small that a formal plan would be overhead.
• You are only seeking code generation or code review, rather than task decomposition and project planning.

In those cases, use brainstorming, design, or coding-focused skills instead.

Do I have to use the default docs/superpowers/plans/ path?

No. The upstream guidance suggests saving plans to:

• docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

But it explicitly notes that user preferences for plan location override this default. You can keep plans in any directory or naming scheme that fits your repository and documentation standards.

Can I use writing-plans for non-code projects?

The skill is written with software projects and codebases in mind, including file mappings and tests. However, the core ideas—breaking work into small tasks, mapping responsibilities, and checking completeness—can be adapted to other technical workflows. It will be most effective where there is at least some notion of files, tests, or documentation to update.

How does writing-plans help with onboarding and handoffs?

Because writing-plans assumes the implementer has zero context for your codebase and questionable taste, it encourages you to:

• Explain where code should live and why.
• Make tests and docs explicit.
• Remove ambiguity from tasks.

This makes it much easier to hand off work to new team members, contractors, or subagents. They can follow the plan directly instead of reverse-engineering intent from a spec.

How does writing-plans relate to project management tools?

writing-plans complements, rather than replaces, project management tools:

• It gives you a structured written plan that explains how to implement a spec at the code and file level.
• You can then map plan tasks into tools like Jira, GitHub Issues, or Linear.

The skill sits at the intersection of project management, workflow templates, and technical report writing, giving you a reusable pattern for consistent implementation plans.

Can I use only the reviewer prompt without the full skill?

Yes. The plan-document-reviewer-prompt.md file can be used independently as a review template for any plan-like document. You can dispatch it as a subagent prompt to:

• Review plans written with writing-plans.
• Check plans created by other processes or tools.

However, you will get the most consistent results when both the plan and the review are aligned with the writing-plans workflow.