writing-plans

Overview of writing-plans skill

What the writing-plans skill does

The writing-plans skill helps you turn a feature spec or requirements document into a detailed implementation plan before coding starts. Its core job is not idea generation; it is producing a buildable, reviewable plan that assumes the implementer has little codebase context and still needs clear file-level guidance, testing steps, and task sequencing.

Who should use writing-plans

This skill is best for engineers, tech leads, and agent-driven workflows that already have a scoped requirement and now need an execution plan for Requirements Planning. It is especially useful when the work spans multiple files, touches tests and docs, or will be handed off to someone other than the original spec author.

The real job-to-be-done

Users of writing-plans usually want to reduce implementation guesswork. The value is not just “make a plan,” but “make a plan that a capable engineer can follow without hidden assumptions.” That includes what files to touch, how to break work into bite-sized tasks, what to test, and where scope should be split before implementation begins.

What makes this skill different from a generic prompt

The writing-plans skill is opinionated in ways that matter:

• it pushes a scope check before decomposition
• it requires mapping file responsibilities before task writing
• it favors small, testable increments over broad phases
• it assumes weak domain context on the implementer side
• it includes a reviewer prompt for checking whether the plan is actually implementable

That makes it stronger than a one-line “write me an implementation plan” prompt when you care about handoff quality.

When writing-plans is a strong fit

Use writing-plans when you have:

• a written spec, ticket, or requirements doc
• a multi-step change with meaningful implementation detail
• a need to coordinate code, tests, and documentation
• a repository where file boundaries and sequencing matter

If you only need a quick outline or rough estimate, this may be heavier than necessary.

How to Use writing-plans skill

writing-plans install context

The repository does not expose a dedicated package-level installer inside the skill itself, so the practical writing-plans install path is to add the parent skill collection and invoke this skill from there:

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

If your environment uses a different skill loader, install the obra/superpowers collection and select writing-plans from skills/writing-plans.

Read these files first

For fast evaluation, start with:

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md gives the actual planning workflow. The reviewer prompt shows the quality bar the plan is expected to meet, which is useful before you commit to using the skill in production.

What input the skill needs

writing-plans usage is best when you provide:

• the source spec or requirements
• the target repository or codebase area
• any constraints on architecture, tooling, deadlines, or backward compatibility
• the desired plan output location if you do not want the default
• whether the work should be split into multiple independent plans

Without a real spec, the skill tends to produce plausible structure but weaker implementation guidance.

Start with the required announcement

The upstream instructions explicitly ask the agent to announce:

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

If you are integrating this into an agent workflow, keep that line. It makes invocation visible and reduces ambiguity about which planning standard is being applied.

Use it before code, ideally in a dedicated worktree

The skill is designed for pre-implementation planning and expects to run in a dedicated worktree created upstream by a brainstorming workflow. Even if you do not use that exact companion setup, the intent matters: plan in an isolated context before making code edits, so the plan is a deliberate artifact rather than a byproduct of coding.

How to turn a rough goal into a strong prompt

Weak prompt:

• “Make a plan for adding billing.”

Stronger prompt:

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

Why this works:

• it names the spec
• it points to likely files or modules
• it states constraints that affect decomposition
• it invites scope splitting instead of forcing one oversized plan

Follow the skill's planning sequence

A good writing-plans guide should follow the repository's implied order:

1. check whether the spec should be split into separate plans
2. map files to responsibilities before task breakdown
3. write bite-sized implementation tasks
4. include tests, docs, and validation steps
5. review the finished plan against the spec

Skipping the file-structure step is the most common way to get vague tasks.

What good output should include

A strong plan from writing-plans for Requirements Planning should usually contain:

• the plan objective and linked spec
• the files to create or modify
• why each file exists or changes
• tasks small enough to complete and verify independently
• testing guidance, not just coding steps
• doc or migration updates if relevant
• enough detail that another engineer would not get stuck

If the output is mostly thematic phases like “backend,” “frontend,” “QA,” it is probably too coarse.

Default plan location and when to override it

The skill suggests saving plans to:

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

Override this when your repo already has a planning convention, such as docs/plans/ or specs/implementation/. The important part is consistency and a path that reviewers can find later.

How to use the reviewer prompt

After drafting the plan, use plan-document-reviewer-prompt.md as a second-pass review template. Its review criteria are practical:

• completeness
• spec alignment
• task decomposition
• buildability

This is a useful differentiator of the writing-plans skill: it does not stop at generation, it gives you a lightweight acceptance check for the plan artifact.

Practical workflow that works well

A reliable workflow looks like this:

1. gather the spec and repo context
2. run writing-plans
3. inspect whether the plan split is correct
4. review file boundaries and task granularity
5. run the plan reviewer prompt
6. revise the plan before implementation begins

This makes the skill most valuable as a planning gate, not just a writing convenience.

writing-plans skill FAQ

Is writing-plans good for beginners?

Yes, if a beginner already has a reasonably concrete spec. The skill compensates for missing codebase context by forcing explicit file and testing guidance. It is less helpful when the real problem is still ambiguous product thinking.

How is this different from asking an AI for an implementation plan?

Generic prompts often produce polished but shallow plans. writing-plans is more useful because it pushes file-level decomposition, testability, and implementer handoff quality. That usually means less rework once coding starts.

When should I not use writing-plans?

Skip it when:

• the change is tiny and local
• you are still deciding product scope
• you need architectural exploration more than execution planning
• the work is intentionally experimental and likely to change immediately

In those cases, lightweight notes may be better than a formal plan.

Does it require a specific stack or framework?

No. The skill is process-oriented rather than framework-specific. Its advice is portable across stacks because it focuses on decomposition, file responsibilities, testing, and reviewability.

Can writing-plans handle large specs?

Yes, but only if you respect the scope-check step. The source explicitly warns that multiple independent subsystems should usually become separate plans. If you force one giant plan, task quality usually drops.

Is writing-plans enough by itself for Requirements Planning?

For implementation-focused Requirements Planning, often yes. For discovery-stage requirements, no. It assumes you already know what should be built and now need a reliable path to build it.

How to Improve writing-plans skill

Give stronger repository context

The easiest way to improve writing-plans results is to name likely directories, modules, or files. The skill wants to map file responsibilities early; if you provide likely touchpoints, the output becomes more concrete and less generic.

Separate independent subsystems up front

If your spec mixes unrelated concerns, split them before asking for a final plan. Example:

• auth changes
• billing changes
• admin UI changes

These may ship together product-wise but still deserve separate plans if they can be implemented and tested independently.

Ask for file responsibility mapping explicitly

If the first draft is vague, request:

• “List each file to add or modify and state its responsibility before writing tasks.”

This aligns tightly with the skill's structure and usually fixes fuzzy decomposition.

Force smaller task granularity

A common failure mode is tasks that are too large to implement safely. Ask for:

• tasks that produce testable progress
• clear boundaries per task
• explicit validation after each major change

This is where writing-plans usage improves most: smaller tasks are easier to review, assign, and execute.

Make testing requirements concrete

Do not ask only for “include tests.” Instead specify:

• what level of tests matter
• what existing test suites should be updated
• whether migration, integration, or regression checks are required

The skill already values testing, but better constraints make the plan much more useful.

Improve the first draft with reviewer-driven iteration

Use the reviewer template as an editing tool, not just a final gate. After the first plan, ask:

• what requirements are missing from the spec
• where tasks are not actionable
• where the implementer could get stuck
• whether there is scope creep

This produces a sharper second draft than broad “improve the plan” prompts.

Watch for these common failure modes

The writing-plans skill is weaker when:

• the spec is incomplete
• file boundaries are guessed, not grounded in the repo
• tasks describe outcomes without implementation steps
• testing is mentioned but not tied to code changes
• one oversized plan hides multiple independent deliverables

If you see these, revise inputs before blaming the skill.

Add constraints that change implementation choices

Useful constraints include:

• backward compatibility requirements
• performance expectations
• migration safety
• deployment order
• documentation obligations
• no-new-dependency rules

These details help writing-plans for Requirements Planning generate a plan that fits your environment rather than a generic ideal.

Compare the plan against actual handoff needs

The right quality test is simple: could another engineer with low context implement from this document without repeated clarification? If not, improve the plan until file choices, task boundaries, and validation steps are explicit.

Keep the plan DRY and implementation-focused

The source guidance emphasizes DRY, YAGNI, TDD, and frequent commits. In practice that means removing duplicate tasks, avoiding speculative work, and preferring increments that can be coded and verified quickly. Those principles matter more to output quality than adding more prose.