Overview
Write a comprehensive implementation plan, assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to modify for each task, code, tests, documentation they may need to consult, and how to test. Break the entire plan into small-step tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are experienced developers but know almost nothing about our toolchain and problem domain. Assume they are not very good at test design.
At the start, announce: "I am using the writing-plans skill to create an implementation plan."
Context: This skill should be 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 the brainstorming phase. If not, suggest splitting it into independent plans—one per subsystem. Each plan should be able to independently produce working, testable software.
File structure
Before defining tasks, first list the files to be created or modified and the responsibility of each file. This is where decomposition decisions are locked in.
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code that fits into context at one time—the more focused the files, the more reliable your edits. Prefer small, focused files over large files that take on too much functionality.
- Files that change together should be placed together. Split by responsibility, not by technical layer.
- In an existing codebase, follow existing patterns. If the codebase uses large files, do not unilaterally refactor—but if the file you are modifying has become unmanageable, including a split in the plan is reasonable.
This structure determines task decomposition. 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 minimum code to make the test pass" - one step
- "Run the test to confirm it passes" - one step
- "Commit" - one step
Plan document header
Each 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 defects—never write them:
- "TBD", "TODO", "implement later", "add details"
- "Add appropriate error handling" / "Add validation" / "Handle edge cases"
- "Write tests for the above code" (without actual test code)
- "Similar to task N" (duplicated code—engineers may not read tasks in order)
- Steps that only describe what to do without showing how to do it (code steps must have code blocks)
- References to types, functions, or methods that are not defined in any task
Notes
- Always use exact file paths
- Every step includes complete code—if the 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 subagent dispatch.
1. Spec coverage: Browse every section/requirement in the spec. Can you point to the task that implements it? List all 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 types, method signatures, and property names used in later tasks match those defined in earlier tasks? If task 3 calls it clearLayers() but task 7 calls it clearFullLayers() , that is a bug.
If you find issues, 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, provide 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, with review between tasks and fast iteration
2. Inline execution - Execute tasks in the current session using executing-plans, with batched execution and 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
- Batched execution with checkpoints for review