Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Break the whole plan into small step tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are an experienced developer but know almost nothing about our toolset or problem domain. Assume they are not great at test design.
Announce at the start: "I'm using the writing-plans skill to create the implementation plan."
Context: This skill should run in a dedicated worktree (created by the brainstorming skill).
Plan save location: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- (The user's preference for plan location takes precedence over this default.)
Scope Check
If the spec covers multiple independent subsystems, it should have been split into sub-project specs during brainstorming. If it wasn't, suggest splitting it into separate plans—one per subsystem. Each plan should produce working, testable software on its own.
File Structure
Before defining tasks, list the files that will be created or modified and each file's responsibility. This is where you lock in decomposition decisions.
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code that fits in context at once; the more focused the file, the more reliable your edits. Prefer small, focused files over large files that take on too much functionality.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In an existing codebase, follow existing patterns. If the codebase uses large files, don't unilaterally refactor—but if a file you are modifying has become unmanageable, including a split in the plan is reasonable.
This structure determines the task breakdown. Each task should produce an independent, meaningful change.
Small-Step Task Granularity
Each step is one action (2-5 minutes):
- "Write the failing test" - one step
- "Run it to confirm it fails" - one step
- "Implement the minimal code to make the test pass" - one step
- "Run the test to confirm it passes" - one step
- "Commit" - one step
Plan Document Header
Every plan must start with this header:
# [功能名称] 实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** [一句话描述要构建什么]
**架构：** [2-3 句话描述方案]
**技术栈：** [关键技术/库]
---
Task Structure
### 任务 N：[组件名称]
**文件：**
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`
- [ ] **步骤 1：编写失败的测试**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **步骤 2：运行测试验证失败**
运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，报错 "function not defined"
- [ ] **步骤 3：编写最少实现代码**
```python
def function(input):
return expected
```
- [ ] **步骤 4：运行测试验证通过**
运行：`pytest tests/path/test.py::test_name -v`
预期：PASS
- [ ] **步骤 5：Commit**
```bash
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 the engineer needs. The following areplan 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 code" (without actual test code)
- "Similar to Task N" (duplicate code—engineers may not read tasks in order)
- Steps that only describe what to do without showing how (code steps must have code blocks)
- References to types, functions, or methods not defined in any task
Notes
- Always use exact file paths
- Every step includes complete code — if a step involves a code change, show the code
- Exact commands and expected output
- DRY, YAGNI, TDD, frequent commits
Self-Review
After writing the complete plan, review the spec with fresh eyes and check the plan against it. This is a checklist you perform yourself — not a subagent dispatch.
1. Spec coverage: Skim every section/requirement in the spec. Can you point to a task that implements it? List any omissions.
2. Placeholder scan: Search the plan for red flags — any pattern from the "No Placeholders" section above. Fix them.
3. Type consistency: Do the type, method signature, and property names used in later tasks match those defined in earlier tasks? It is called clearLayers() in Task 3 but called clearFullLayers() in Task 7 — that is a bug.
If you find problems, fix them inline. No need to re-review — fix them and keep going. If you find a requirement in the spec with no corresponding task, add a task.
Execution Handoff
After saving the plan, offer execution options:
"The plan is complete and saved to docs/superpowers/plans/<filename>.md. Two execution approaches:
1. Subagent-driven (recommended) - Dispatch a new subagent for each task, review between tasks, fast iteration
2. Inline execution - Execute tasks in the current session with executing-plans, in batches with checkpoints
Which approach do you choose?"
If you choose subagent-driven:
- Required sub-skill: Use superpowers:subagent-driven-development
- One new subagent per task + two-stage review
If you choose inline execution:
- Required sub-skill: Use superpowers:executing-plans
- Batch execution with checkpoints for review