---
name: superpower-writing-plans
description: Internal fork of superpowers:writing-plans with the "Which execution approach?" handoff gate stripped. Use when a parent skill needs a bite-sized, TDD-ready implementation plan written to disk without user-facing confirmation breaks.
user-invocable: false
---

# Writing Plans (Internal, Gate-Free)

Write task-level implementation plans that tell the TDD executor **what to do**, not **how to write the code**. The executor is `feature-tdd` (Claude itself with full context), not a mechanical copy-paster — so the plan captures file boundaries, test intent, API shapes and completion criteria, and lets the executor produce the actual code in the red-green cycle. DRY. YAGNI. TDD. Frequent commits.

**Do NOT dump full file contents (pom.xml, entity classes, config files) into the plan.** The plan and the code end up as two sources of truth that drift; 2000+ line plans also waste context. Code is produced during TDD, not pre-written here.

**Caller contract:** the parent skill passes in (or this skill derives) a plan output path and a spec file path. Once the plan is written and self-reviewed, control returns to the caller. This skill does NOT ask the user to choose an execution mode; the caller decides.

**Save plans to:** the caller-provided path (default `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`).

## Scope Check

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

## 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.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns. 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:**

```markdown
# [Feature Name] Implementation Plan

> **Execution:** Parent skill `feature-tdd` executes 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

Each task is a unit of red-green-commit. Capture intent and boundaries — leave code to TDD.

````markdown
### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/File.java`
- Modify: `exact/path/to/Existing.java:123-145`
- Test: `tests/exact/path/to/FileTest.java`

**API shape (只写需要约束实现的签名；内部实现留给 TDD):**
- `LoginService#login(LoginRequest req) : LoginResponse`
- `throws AccountLockedException when iLoginFailCount ≥ 5 within tLockUntil window`

- [ ] **Step 1: 写失败测试**
  - 测试名: `LoginServiceTest#loginWithBadPassword_incrementsFailCount_returns40101`
  - 意图: 错误密码 → `iLoginFailCount += 1`；第 5 次 → 设置 `tLockUntil = now + 15min`；返回码 40101
  - 子会话确认 FAIL（函数/类不存在）

- [ ] **Step 2: 实现最小代码**
  - 目标: 让 Step 1 测试通过；不多做
  - 涉及文件: `LoginService.java`, `SftLoginInfoMapper.java`

- [ ] **Step 3: 子会话验证 PASS**

- [ ] **Step 4: Commit**
  - `git add <文件>`
  - `git commit -m "feat(sys): 登录失败计数 + 锁定 REQ-SYS-001"`
````

**允许的代码块场景**（少数例外，需要写死而非让 TDD 自由发挥的内容）：

- **DDL / migration 文件**：`V_n__*.sql` 的 ALTER/CREATE 语句——因为 schema 是事实源、不是 TDD 的"红绿"产物
- **合同级常量**：API 错误码表、JWT claim 名、Redis key 模式——这些跨模块被消费，必须在 plan 锁定
- **测试的断言形状**（可选）：如果一句话说不清"测什么"，给个 3-5 行断言 sketch 是 OK 的

除此之外一律用散文+签名描述，**不贴完整文件**。

## 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"
- **`【人工填写：...】`** — this marker is A-phase only (`docs/01~10`, `CLAUDE.md`, `.env.local`). It must NEVER appear in B-phase plans. If you need a concrete value: (a) look it up in `.env.local` / `docs/07` / `CLAUDE.md` / existing code and cite the source in the plan, or (b) ask the user via `AskUserQuestion` and record the answer. The plan is CC's executable artifact, not a user-review doc.
- "Add appropriate error handling" / "add validation" / "handle edge cases"（具体到哪些错误码 / 哪些字段）
- "Similar to Task N"（相似任务各自写清楚测试意图 + 完成判据，不互相链接）
- References to types, functions, or methods not defined in any task（类/方法首次出现的 task 要给出 API 签名）

> 散文级"做什么"是 OK 的——执行器（feature-tdd）会在 TDD 循环里决定"怎么写"。plan 的义务是**约束范围**，不是**替 TDD 写代码**。

## Remember

- Exact file paths always
- Exact commands with expected output (for test runs and git ops)
- API signatures / class names / error codes / contract values — 必须写死
- Internal implementation code — 不写；留给 TDD 阶段
- DRY, YAGNI, TDD, frequent commits

## 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, not a user approval gate.

**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 (including `【人工填写：...】`). Fix them: resolve by file lookup, raise a `AskUserQuestion`, or rewrite the step to be concrete.

**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 re-review — just fix and move on. If you find a spec requirement with no task, add the task.

## Terminal State

Once the plan file is written and self-reviewed, return control to the caller. Do NOT ask the user to pick an execution approach; the caller decides how to execute.