BubbleBuffer/writing-plans

Writing Plans

Overview

Write implementation plans that give implementer subagents enough context to make correct edits without forcing the planner to do every grep/read/edit operation itself.

Plans should be precise about target behavior, files, anchors, verification, and task boundaries. For existing files, prefer compact target-state sketches over exact line ranges or full-file replacement instructions. For new files, provide complete intended content.

Assume implementers are skilled developers with isolated context. They can read target files, match semantic anchors, apply local target state, and inspect diffs, but they should not have to make product or architecture decisions.

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

Context: This runs on the feature branch prepared by using-git-branches. If you are not on the user-approved branch, stop and invoke using-git-branches first.

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

• (User preferences for plan location override this default)

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem or recommend the User spend some more time brainstorming. Each plan should produce working, testable software on its own.

Process

You write the plan directly, using researcher subagents to explore the codebase as needed.

1. Research the Codebase

Dispatch researcher subagents to understand the codebase before writing:

Task(
  "Explore [area]",
  subagent_type="superpawers-researcher",
  prompt="Find files handling [feature area]. Map key functions and locations."
)

Dispatch multiple researchers in parallel for independent questions. Examples:

• "Find files handling [feature area]. Map key functions/classes, nearby literals, and likely edit anchors."
• "Trace data flow from [entry] to [output]. Report file paths and semantic anchors."
• "What testing patterns does this codebase use? Find example tests and commands."

Wait for ALL researchers to report before synthesizing.

2. Write the Plan

Write the plan file following the format below. Use exact file paths, target-state sketches for existing files, complete content for new files, exact verification commands, and expected outcomes.

3. Review the Plan

Dispatch the generalized reviewer subagent with the plan quality prompt:

Task(
  "Review implementation plan",
  subagent_type="superpawers-reviewer",
  prompt=<rendered plan-document-reviewer-prompt.md with plan path, spec path>
)

The reviewer will:

1. Read the plan and spec
2. Check spec coverage, task flow, anchor quality, sketch clarity, placeholders, and natural-language note quality
3. Return a review report without modifying files

Handling Review Results

PASS: Present plan summary to user and offer execution choice. Do not read the full plan — show the path, goal, task count, and key decisions.

FAIL (simple issues): Simple issues are: typos, naming inconsistencies, dead references, missing specificity. Fix these directly in the plan file, then present summary and offer execution choice.

FAIL (architectural/spec issues): Architectural issues indicate overscoping or unclear specs — things that require design judgment. Present the findings to the user:

"The plan reviewer found some issues that need your input: [List issues from the reviewer's report]

These seem to stem from [ambiguous spec / scope overlap / unclear requirements]. What are your thoughts?"

Discuss with the user, then fix the plan directly based on their answers.

Prompt Templates

• plan-document-reviewer-prompt.md — task prompt for dispatching the generalized reviewer to check implementation plan quality

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
• You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
• Files that change together should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

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

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

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

### Task N: [Component Name]

**Files:**
- Modify: `exact/path/to/existing.py` — update [function/class/call site] using anchors `[anchor names/literals]`
- Create: `exact/path/to/new_file.py` — [responsibility]
- Test: `tests/exact/path/to/test.py`

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

For new tests, provide complete test code or a target-state sketch anchored to existing test names/patterns.

```python
# ... existing imports ...

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

# ... existing code ...
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL because [specific behavior is missing]

- [ ] **Step 3: Apply target-state implementation**

For existing files, show the local target state with semantic anchors and elisions:

```python
# ... existing code ...

def existing_function(existing_arg):
    # existing nearby behavior that anchors the edit
    target_value = new_helper(existing_arg)
    return target_value

# ... existing code ...
```

For new files, provide complete file content.

- [ ] **Step 4: Inspect the diff against the sketch intent**

Run: `git diff -- exact/path/to/existing.py tests/exact/path/to/test.py`
Expected: diff only changes the planned anchored areas and preserves elided code.

- [ ] **Step 5: Run test to verify it passes**

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

- [ ] **Step 6: Commit**

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

Target-State Sketch Rules

For existing files:

• Name the exact file path.
• Group multiple edits in the same file into one local sketch when practical.
• Include semantic anchors such as function names, class names, call sites, nearby literals, or existing test names.
• Use language-appropriate elision markers such as // ... existing code ..., # ... existing code ..., or <!-- ... existing content ... --> to mark preserved regions.
• Show real code for behaviorally important logic.
• Allow natural-language notes only when they are concrete, local, mechanical, and derivable from nearby code without design judgment.

For new files:

• Provide complete intended content. There is no existing context to anchor to.

These are plan failures:

• Vague placeholders: "TBD", "TODO", "implement later", "fill in details".
• Vague behavior: "add validation", "handle errors", "write tests for this" without exact expected behavior.
• Ambiguous anchors where multiple locations could match.
• Natural-language notes that require product, architecture, naming, or error-handling decisions.
• Exact line-range dependence for existing files unless the line number is only supplementary.

Remember

• Exact file paths always.
• Target-state sketches for existing files; complete content for new files.
• Exact commands with expected outcomes.
• Implementers read files, resolve anchors, apply local target state, and inspect diffs.
• DRY, YAGNI, TDD, frequent commits.

Execution Handoff

After the plan is approved (review PASS or issues resolved), hand off to execution.

"Plan complete and saved to .superpawers/plans/<filename>.md. Next step: subagent-driven-development."

• REQUIRED SUB-SKILL: Use subagent-driven-development to execute the plan.
• Fresh subagent per task, two-stage review (spec compliance then code quality), final reviewer, then verifier.
• If the user explicitly requests hands-on execution instead, pause and confirm — this library does not provide a manual execution skill, and inline execution bypasses the review gates.