writing-plans

name	writing-plans
description	Use when you have a spec or requirements for a multi-step task, before touching code

Writing Plans

Purpose

Create implementation plans for technical coding agents that will execute a feature, fix, or refactor in a real codebase. The plan should minimize ambiguity, make dependencies explicit, and provide enough repository-level detail that an agent can carry out the work with limited additional interpretation.

Announce at the start: "I'm using the planning skill to create the implementation plan."

When To Use

Use this skill when:

• the user provides a spec, feature request, bug report, or implementation requirements
• the work will take multiple steps, touch multiple files, or require coordination across code, tests, and docs
• the task should be decomposed before code changes begin
• a technical coding agent will likely execute the resulting plan

Do not use this skill for:

• tiny, low-risk edits that do not benefit from a written plan
• purely exploratory brainstorming with no clear implementation target
• direct execution of the work itself

Primary Audience

Write for a capable coding agent operating in an unfamiliar or partially familiar repository.

Assume the agent:

• can edit code, run tests, and inspect files
• understands standard engineering concepts
• does not know this codebase’s architecture, conventions, or domain-specific assumptions
• benefits from explicit file boundaries, exact commands, and concrete test targets
• should not have to infer missing implementation structure if the plan can provide it

The plan should help the agent make correct local decisions without re-planning the entire feature.

Default Output Location

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

If the user specifies a different location, follow the user’s preference.

Planning Standard

Write plans that are:

• execution-ready
• codebase-specific
• concrete about files, interfaces, and validation
• broken into small, checkable increments
• robust against agent misinterpretation

Favor:

• explicit decomposition
• minimal but sufficient implementation detail
• TDD where practical
• small validation loops
• frequent commits when the execution environment uses commits as checkpoints

Do not pad the plan with generic engineering slogans unless they materially affect execution.

Scope Check

Before writing tasks, determine whether the request represents:

• one coherent implementation thread
• several loosely related changes
• multiple independent subsystems that should be planned separately

If the spec spans independent workstreams, recommend splitting into separate plans. Each plan should produce a testable, meaningful increment on its own.

If keeping one plan, define task boundaries so the execution agent can work through them in order without confusion about ownership or sequencing.

Repository Mapping First

Before defining tasks, map the expected file-level surface area.

For each relevant file, specify:

• exact path
• create or modify
• role in the implementation
• notable dependencies or interfaces it connects to

This step should lock in the decomposition before task writing begins.

Guidelines:

• prefer focused files and clear ownership boundaries
• group files by responsibility and change relationship
• follow established repo patterns
• avoid speculative restructuring
• include refactors only when they directly support safe implementation
• if an existing file is overly large or coupled, it is acceptable to plan a focused split, but explain why

If the implementation depends on discovering unknown files during execution, name the likely search targets or patterns the agent should inspect.

Agent-Oriented Task Granularity

Break the work into small tasks and even smaller checkbox steps.

Target size:

• each checkbox step should usually be one action
• each step should usually take only a few minutes of execution time
• each task should represent one coherent unit of code change or validation

Good step types:

• inspect an existing module or interface
• write or update a failing test
• run a targeted test command and confirm the current behavior
• implement the minimal code needed for that test
• rerun tests
• update related docs or configuration
• commit the checkpoint if commits are part of the workflow

Avoid multi-action checkboxes that mix discovery, implementation, and verification into one step.

Required Plan Header

Every plan must begin with this exact structure:

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use mojosmind:subagent-driven-development (recommended) or mojosmind:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds or changes]

**Architecture:** [2-3 sentences describing the implementation approach and where it fits in the codebase]

**Tech Stack:** [Key technologies, frameworks, libraries, test tools, and commands used by this work]

---

Plan Structure

Organize the plan into tasks that reflect actual execution order.

Each task should:

• define a narrow goal
• list exact files involved
• include checkbox steps in the intended order
• show concrete code or command examples where needed
• include validation steps before moving on

Prefer plans where later tasks build on earlier completed states instead of requiring the agent to mentally merge parallel unfinished work.

Task Format

Use this structure for each task:

### Task N: [Task Name]

**Objective:** [What this task accomplishes]

**Files:**
- Create: `path/to/new_file.py`
- Modify: `path/to/existing_file.py`
- Test: `tests/path/to/test_file.py`

**Notes:**
- [Key repository convention, dependency, interface contract, or constraint the agent must respect]

- [ ] **Step 1: Inspect the existing implementation surface**

Look at:
- `path/to/existing_file.py`
- `path/to/related_interface.py`

Confirm:
- where the behavior currently lives
- which public function, class, or module should own the change
- whether an existing test file should be extended or a new one added

- [ ] **Step 2: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 3: Run the targeted test and confirm failure**

Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
Expected: FAIL with `[expected reason]`

- [ ] **Step 4: Implement the minimal code change**

```python
def function(input):
    return expected
```

- [ ] **Step 5: Re-run the targeted test**

Run: `pytest tests/path/test_file.py::test_specific_behavior -v`
Expected: PASS

- [ ] **Step 6: Run any related verification**

Run: `pytest tests/path/test_file.py -v`
Expected: PASS

- [ ] **Step 7: Commit the checkpoint**

```bash
git add tests/path/test_file.py src/path/file.py
git commit -m "feat: add specific behavior"
```

Required Detail Level

Every task must include the real execution details an agent needs.

Include:

• exact file paths
• exact test paths
• concrete commands
• expected failure and success states
• code snippets when the step changes code shape, interfaces, or behavior
• explicit ownership of where the change should live
• notes about surrounding conventions when they are relevant to success

If applicable, also include:

• migrations
• config changes
• API contract updates
• fixture changes
• schema changes
• generated files
• documentation updates
• rollout or cleanup steps

Do not assume the executing agent will discover these on its own if the spec already implies them.

No Placeholders

These are plan failures and must not appear in the final plan:

• TBD
• TODO
• implement later
• fill in details
• add appropriate error handling
• add validation
• handle edge cases
• write tests for the above
• similar to Task N

Also avoid:

• vague instructions with no concrete code target
• steps that say what to do without showing how to do it
• references to functions, types, files, or commands not defined elsewhere in the plan
• hand-waving around test coverage, integration points, or expected outputs

If a behavior needs error handling, validation, or edge-case coverage, specify the exact cases and where they belong.

Consistency Rules

The plan must be internally consistent and execution-safe.

Check for:

• exact function, method, type, and property names matching across tasks
• commands that refer to the same files listed in the task
• tests that exercise the behavior described in the spec
• interfaces defined before downstream usage
• implementation order that respects dependencies
• file ownership that does not conflict across tasks

A later task must not depend on undefined code or unexplained earlier decisions.

Coding-Agent Guidance

When useful, include short agent-facing guidance such as:

• which existing abstraction to extend instead of introducing a new one
• where to preserve backward compatibility
• which helper, service, or module is the intended change point
• whether a refactor is in scope or explicitly out of scope
• whether generated code should be edited directly or via the generator source
• whether broader test suites are required before completion

Keep this guidance operational. Do not include generic commentary that does not change behavior.

Stop-And-Ask Checkpoints

Include explicit stop-and-ask checkpoints when execution should pause for user confirmation instead of continuing autonomously.

Use a checkpoint when:

• the spec is ambiguous in a way that could change architecture or public behavior
• multiple reasonable implementation paths exist with meaningful product or maintenance tradeoffs
• the change may break backward compatibility
• the work touches migrations, destructive data changes, auth, billing, permissions, security-sensitive logic, or external contracts
• the agent discovers repo reality that materially conflicts with the original spec
• the next step would require a broad refactor that was not clearly in scope
• test failures or integration results suggest the intended behavior is unclear rather than simply broken

For each checkpoint, state:

• what the agent learned
• why continuing without confirmation is risky
• the concrete decision that needs approval
• the available options, if there is more than one reasonable path
• the recommended option, with a short reason

Format checkpoints like this:

### Stop-And-Ask Checkpoint: [Short Name]

**Trigger:** [What condition causes the pause]

**Why this needs confirmation:**
- [Risk, ambiguity, or tradeoff]

**Decision needed:**
- [Exact question the user or reviewer must answer]

**Options:**
1. `[Option A]` - [Impact]
2. `[Option B]` - [Impact]

**Recommended:** `[Option X]` - [Short reason]

Do not add checkpoints for routine implementation decisions that the agent can safely resolve from the codebase and spec. Only use them for decisions that could materially change scope, behavior, or risk.

Self-Review

After drafting the full plan, review it before saving.

Check:

1. Spec coverage: every meaningful requirement maps to at least one task.
2. Placeholder scan: remove vague wording and replace it with execution detail.
3. Consistency: verify names, paths, commands, interfaces, and task order all line up.
4. Agent executability: confirm a technical coding agent could follow the plan with minimal extra interpretation.
5. Risk gaps: identify any migration, integration, config, or testing work implied by the change but not yet represented.

If you find gaps, fix them directly in the plan.

Execution Handoff

After saving the plan, offer the user these execution options:

Plan complete and saved to `docs/mojosmind/plans/<filename>.md`.

Two execution options:

1. Subagent-Driven (recommended)
I dispatch a fresh subagent per task, with review between tasks for fast iteration.

2. Inline Execution
I execute the tasks in this session using executing-plans, with checkpointed progress.

Which approach?

**Which approach?"**

**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Fresh subagent per task + two-stage review

**If Inline Execution chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
- Batch execution with checkpoints for review