朱子纯 / erp-workflow-plugin

SKILL.md 7.15 KB

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 erp-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:

# [Feature Name] Implementation Plan

> **Execution:** Parent skill `erp-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.

### 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 的——执行器（erp-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.