writing-plans Checked

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans 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]

**Spec:** [path to the spec/design doc this plan implements — the plan

argues from the spec, so the spec travels with it; executors read both]

Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,

naming and copy rules, platform requirements — one line each, with exact

values copied verbatim from the spec. Every task's requirements implicitly

include this section.]

---

## Task Structure

### Task N: [Component Name]

**Files:**

• Create: exact/path/to/file.py
• Modify: exact/path/to/existing.py:123-145
• Test: tests/exact/path/to/test.py

**Interfaces:**

• Consumes: [what this task uses from earlier tasks — exact signatures]
• Produces: [what later tasks rely on — exact function names, parameter

and return types. A task's implementer sees only their own task; this

block is how they learn the names and types neighboring tasks use.]

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

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

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

Run: pytest tests/path/test.py::test_name -v

Expected: FAIL with "function not defined"

• [ ] **Step 3: Write minimal implementation**

def function(input):
    return expected

• [ ] **Step 4: Run test to verify it passes**

Run: pytest tests/path/test.py::test_name -v

Expected: PASS

• [ ] **Step 5: Commit**

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

## No Placeholders

Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
- Steps that describe what to do without showing how (code blocks required for code steps)
- References to types, functions, or methods not defined in any task

## Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**

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

**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints

**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