prd-to-tasks

PRD → Tasks

A structured transformation pipeline from PRD to executable engineering tasks. Core value:Codebase-aware task decomposition + Risk-driven workflow routing。

A structured pipeline from PRD to executable engineering tasks. Core value: codebase-aware task breakdown + risk-driven workflow routing.

Dependencies · Dependencies

This skill is theend-to-end development pipelinesecond half of. If you don't have a PRD yet, first use the /prd skill to generate one.

This skill is the second half of an end-to-end development pipeline. If you don't have a PRD yet, use the /prd skill to generate one first.

Install `/prd` · Install `/prd`

npx skills add github/awesome-copilot@prd -g -y

Source · Source: https://skills.sh/github/awesome-copilot/prd（17.8K installs，MIT License）

Full Pipeline · Full Pipeline

想法 / 业务需求
       │
       ▼
  /prd  ──────────────────────────────────────────────────────────
  Phase 1: Discovery 访谈（问题 / 成功指标 / 约束）
  Phase 2: Analysis & Scoping（用户流 / Non-Goals）
  Phase 3: 生成 PRD 文档（Executive Summary / User Stories /
            Technical Specs / Risk Analysis）
       │
       │  产出：PRD 文档（Markdown）
       ▼
  /prd-to-tasks  ──────────────────────────────────────────────────
  Phase 0: PRD 摄取（粘贴 / 飞书链接 / 本地文件）
  Phase 1: 范围澄清 + 风险定级（🔴 / 🟡 / 🟢）
  Phase 2: 代码库深度扫描（受影响文件 / 接口 / DB / MQ）
  Phase 3: Spec 生成（设计文档 → docs/superpowers/specs/）
  Phase 4: 任务拆解（带路径 + 行号的可执行任务清单）
  Phase 5: 工作流路由（→ cross-verified / superpowers 序列 / direct）
       │
       ▼
  编码实现（由路由决定走哪条 superpowers 流程）
       │
       ▼
  代码审查 → 合并 → 上线

How to Chain · How to Chain `/prd` → `/prd-to-tasks`

Step 1: call /prd, complete the three-phase interview, and obtain the PRD document.

/prd

/prd After it ends, you will get a structured Markdown PRD containing: Executive Summary, User Stories, Technical Specifications, Risks & Roadmap.

Step 2: feed the PRD content to /prd-to-tasks. There are three ways:

Method	Operation
Paste text(most common)	`/prd-to-tasks` then directly paste the full PRD text
Local file(PRD already saved)	`/prd-to-tasks docs/prd/my-feature.md`
Feishu link(PRD is in Feishu)	`/prd-to-tasks https://feishu.cn/docx/xxx`

Step 3：/prd-to-tasks starts from Phase 0, ingests the PRD, then restates the core business goals, and after you confirm, proceeds to Phase 1 scope clarification.

Key：/prd-to-tasks will automatically route to the corresponding coding workflow based on the risk rating (Phase 1.3), with no need for you to manually select subsequent steps.

What Problem This Skill Solves · What Problem This Skill Solves

Tasks written by generic spec-driven-development are like "implement user login feature → modify UserService" — when it comes to implementation, you still have to spend a lot of time finding the code.

Generic spec-driven-development produces tasks like "implement user login → modify UserService" — which still require significant time to locate the actual code when executing.

The tasks written by this skill are:

In order-service/internal/service/booking/booking_service.go:142 's CreateBooking method, add a feature flag check, with the flag key being new_order_flow_enabled, use the ID generation helper recorded in the project KB (~/.claude/prd-to-tasks/service-patterns.md) to create a new document ID, write it to the database, and after writing, perform invalidation according to the project cache invalidation protocol — then run the project-agreed build + test command.

This skill produces tasks like:

In the CreateBooking method at order-service/internal/service/booking/booking_service.go:142, add a feature flag check with key new_order_flow_enabled, use the ID generation helper documented in your project's KB (~/.claude/prd-to-tasks/service-patterns.md) to create the new record ID, write to the database, then execute your project's cache invalidation discipline — then run your project's build + test commands.

6-Phase Workflow · 6-Phase Workflow

Phase 0:   PRD 摄取        → 读取文档 / 粘贴文本
           PRD Ingestion    → Read doc / paste text

Phase 1:   范围澄清与风险定级（门控：人工确认）
           Scope Clarity & Risk Classification (gate: human confirmation)

  Phase 1.0: PRD 合理性调研 → 拉取 Lark 关联文档 + 全量加载 KB + 代码定向探针
             PRD Feasibility  → Fetch referenced Lark docs + full KB load + targeted codebase probe

  Phase 1.1–1.4: 识别服务、PM 清单、风险定级（基于 1.0 调研结论）
                  Identify services, PM checklist, risk classification (informed by 1.0)

Phase 2:   代码库深度扫描  → 找受影响的文件、接口、DB 表（全量）
           Deep Codebase Scan → Find affected files, interfaces, DB tables (comprehensive)

Phase 3:   Spec 生成       → 结构化设计文档（门控：人工确认）
           Spec Gen         → Structured design doc (gate: human confirmation)

Phase 4:   任务拆解        → 带路径 + 模式引用的可执行任务（门控：人工确认）
           Task Breakdown   → Executable tasks with paths + pattern references (gate: human confirmation)

Phase 5:   工作流路由      → 决定接下来走哪个 superpowers 流程
           Workflow Route   → Decide which superpowers flow to follow next

Each gated phase must wait for explicit human confirmation before proceeding. Each gated phase must wait for explicit human confirmation before proceeding.

Knowledge Base · Knowledge Base

repo-map、service-patterns and other mapping filesare not hardcoded in this skill——they are a user/team evolvable knowledge base. Reason: every company and every team has a different code repository layout and internal code patterns.

repo-map, service-patterns, etc. are not hardcoded in this skill — they are user/team-evolvable knowledge bases. Reason: every company's code layout and internal patterns are different.

Loading Order · Loading Order

First-found wins; project-level overrides user-level. First-found wins; project-level overrides user-level.

1. <CWD>/.claude/prd-to-tasks/*.md       # 项目级 · Project-level (team-shared via git)
2. ~/.claude/prd-to-tasks/*.md           # 用户级 · User-level (cross-project personal KB)
3. <skill>/references/*.md              # skill 仓库自带 seed · Bundled seed (read-only, industry-neutral)

KB File List (extensible) · KB File List (extensible)

When loading, the skill enumerates all *.md files under the KB directory. Common but not limited to: The skill enumerates all *.md files in the KB directory at load time. Common but not limited to:

File File	Content Content	When read When read
`repo-map.md`	Requirement signal → affected services/repos · Requirement signal → affected services/repos	Phase 1.0 (PRD feasibility validation) + Phase 1.1
`service-patterns.md`	Internal code patterns (ID generation, cache invalidation, MQ topic registration, etc.) · Internal patterns	Phase 1.0(validate PRD compatibility with existing patterns) + Phase 4 task checklist
`<custom>.md`	User-defined (e.g. `state-machine-conventions.md`、`team-owners.md`）· User-custom	Global, the skill decides when to reference it

Bootstrap Protocol

After Phase 0 PRD ingestion, this skill detects the KB directory:

If <CWD>/.claude/prd-to-tasks/ or ~/.claude/prd-to-tasks/ exists → use directly If <CWD>/.claude/prd-to-tasks/ or ~/.claude/prd-to-tasks/ exists → use directly
If neither exists → prompt the user:

KB 目录未找到。建议运行：
  mkdir -p ~/.claude/prd-to-tasks
  cp ~/.claude/skills/prd-to-tasks/references/*.md ~/.claude/prd-to-tasks/
  # 如本 skill 通过 plugin 安装，路径形如 ~/.claude/plugins/cache/<plugin>/skills/prd-to-tasks/references/
然后按你的代码库改写。
或选择跳过（继续但 Phase 1.1 / Phase 4 检查项能力会受限）。

KB directory not found. Recommended:
  mkdir -p ~/.claude/prd-to-tasks
  cp ~/.claude/skills/prd-to-tasks/references/*.md ~/.claude/prd-to-tasks/
  # If installed via plugin: ~/.claude/plugins/cache/<plugin>/skills/prd-to-tasks/references/
Then customize for your codebase.
Or skip (continue but Phase 1.1 / Phase 4 will have reduced capability).

After loading,print the list of KB paths actually in effectto the user, to help spot path misalignment. print the effective KB path list to the user for path-error detection.

Evolution Protocol (recap of Phase 2.3)

The user mustexplicitly agreebefore writing to the KB · Explicit user approval required for KB writes
This skill never writes to the KB silently · This skill never silently writes to KB
Show full diff before write

Phase 0: PRD Ingestion

Three ways to receive a PRD:

A. Feishu/Lark Doc URL（feishu.cn/docx/、feishu.cn/wiki/ etc.）

lark-cli docs +fetch --doc "<url>"

After reading, extract: functional goals, acceptance criteria, interface design, state machine description, launch timeline.

B. Pasted Text: Parse directly and organize the structure.

C. Local File Path: Use the Read tool to read.

After ingestion, summarize thecore business goalsyou understand in 2-3 sentences, and have the user confirm the understanding is correct before continuing. core business goal in 2-3 sentences and ask the user to confirm your understanding before proceeding.

Phase 1: Scope Clarification & Risk Classification

1.0 PRD Feasibility Research

Before starting scope assessment, proactively gather context and judge the technical feasibility of the PRD.Assessing without research = blind assessment: at this point there is no code basis, risk classification may be inaccurate, and many questions in the PM checklist that could have been self-answered will waste the user's time.

Before scope assessment, proactively gather context to evaluate PRD technical feasibility. Evaluating without research = blind assessment: risk classification lacks code evidence, and PM checklist items that could be self-answered will waste the user's time.

Three research layers, execute in order:

A. Lark Document Research

Scan the PRD body and extract all Lark links (feishu.cn/docx/、feishu.cn/wiki/ , etc.), fetch each:

lark-cli docs +fetch --doc "<referenced-url>"

Extract: historical tech decisions, related API docs, constraints from predecessor PRDs.

B. Full KB Load

Readall .md files under the KB directory (including service-patterns.md, not just repo-map.md）： Load all .md files in KB directory (including service-patterns.md, not just repo-map.md):

<CWD>/.claude/prd-to-tasks/*.md  →  repo-map + service-patterns + 所有自定义
~/.claude/prd-to-tasks/*.md       →  用户级 KB

Focus: whether the business flows described in the PRD are compatible with the existing code patterns recorded in the KB (ID generation conventions, cache invalidation protocols, MQ topic registration methods, etc.). Focus: whether the business flows described in PRD are compatible with existing code patterns in KB.

C. Targeted Codebase Probe · Targeted Codebase Probe

For the PRD'score technical claimsconduct a targeted probe. The goal is tovalidate PRD assumptions, not a full scan (full scan is in Phase 2).

Probe the codebase for PRD's core technical claims. Goal: validate PRD assumptions, NOT comprehensive scanning (that's Phase 2).

If the CWD contains relevant code → probe directly, no need to wait for the user to provide a path. Otherwise, ask for the key repository path (the user may answer "provide it later in Phase 2", in which case the assumption is marked as ⚠️ pending validation).

If CWD contains relevant code → probe directly, no need to ask for paths. Otherwise ask for key repo paths (user may say "provide in Phase 2" — that assumption is then marked ⚠️ pending).

# 针对 PRD 声明的核心 symbol/模块做定向 grep · Targeted grep for core symbols/modules from PRD
grep -r "<prд-mentioned-symbol>" <repo>/internal/ --include="*.go" -l

# 检查 PRD 涉及的状态机/枚举是否已存在 · Check if state machines/enums from PRD already exist
grep -r "type.*Status\|State\b" <repo>/internal/ --include="*.go" -l

1.0 Output: PRD Assumption Validation Report · PRD Assumption Validation Report

For each key assumption in the PRD, mark the validation status: For each key PRD assumption, mark validation status:

PRD 假设验证 · PRD Assumption Validation:

✅ 假设成立：<assumption> — 代码/KB/Lark 已有 <symbol>（路径/来源 · path/source: <ref>）
⚠️ 假设待验：<assumption> — 路径未确认，将在 Phase 2 深查
❌ 假设存疑：<assumption> — 与现有代码/KB/Lark 记录冲突（<具体冲突点>）

发现的潜在风险 · Discovered potential risks:
⚠️ <risk> — <why this matters>

Research conclusions inform downstream · Research conclusions inform downstream:

✅ Many → more items in the Phase 1.2 PM checklist can be self-answered, fewer Open Questions
❌ Many → may need to pull in relevant people for discussion before the Phase 1 HARD-GATE, or adjust risk classification
Severe ❌ (fundamental contradiction between PRD and code reality) → pause the process, issue a clear warning to the user, and confirm whether to continue

More ✅ → More PM checklist items self-answerable, fewer Open Questions
More ❌ → May need stakeholder discussion before Phase 1 HARD-GATE, or adjust risk level
Severe ❌ (PRD fundamentally contradicts code reality) → Pause pipeline, warn user explicitly, confirm whether to continue

1.1 Identify Affected Services · Identify Affected Services

Reference references/repo-map.md to map requirements to specific repositories and services: Reference references/repo-map.md to map requirements to specific repos and services:

Typical Requirement Signal · Typical Requirement Signal	Affected Services · Affected Services
User checkout, cart, product detail · User checkout, cart, product detail	`bff-service`
Order status, refunds, wallet · Order status, refunds, wallet	`order-service` (order-api-service / refund-service)
Fulfillment, resource delivery · Fulfillment, resource delivery	`fulfillment-service`(reference KB `repo-map.md` · see KB）
Supplier fulfillment, resource delivery · Supplier fulfillment, resource delivery	`fulfillment-service`
Vouchers, inventory · Vouchers, inventory	`voucher-service`
Payments, collections · Payments, collections	`payment-service`
Cross-service shared models / proto · Cross-service shared models / proto	`shared-models`

1.2 PM Scope-Clarity Checklist · PM Scope-Clarity Checklist

Before asking any technical questions, first list all the information you can infer on your own from PRD + Phase 1.0 research conclusions (Lark docs + KB + code probe) (in the format "I assume..."), then only ask aboutwhat you cannot determine on your own. The more thorough the 1.0 research conclusions, the fewer Open Questions here.

Before asking any technical questions, list everything you can infer from PRD + Phase 1.0 research (Lark docs + KB + codebase probe) ("I assume..." format), then only ask about what you cannot determine yourself. The richer the Phase 1.0 findings, the fewer Open Questions here.

Fill in each item or mark "covered by PRD". Any blank must become an Open Question to the user. Fill in each item or mark "covered by PRD". Any blank must become an Open Question to the user.

#	Dimension · Dimension	Output Requirement · Output Requirement
1	JTBD (Job-to-be-done)	Who uses it in what context, what pain it solves (not "implement X", but "enable Y user in Z context to do W") · Who uses it in what context, what pain it solves (not "implement X", but "enable Y user in Z context to do W")
2	In scope	Enumerable capabilities required this iteration · Enumerable capabilities required this iteration
3	Not Doing	Explicitly excluded capabilities (scope-creep guard) · Explicitly excluded capabilities (scope-creep guard)
4	Deferred to v2	Capabilities deferred + reason · Capabilities deferred + reason
5	Success Metrics · Success Metrics	Business metric (e.g. conversion +X%) + technical metric (e.g. p99 < Yms), both quantifiable · Business metric (e.g. conversion +X%) + technical metric (e.g. p99 < Yms), both quantifiable
6	User Happy Path · User Happy Path	User operation sequence on happy path · User operation sequence on happy path
7	Worst-case Failure · Worst-case Failure	Worst case: what breaks, who/what is harmed, blast radius · Worst case: what breaks, who/what is harmed, blast radius
8	Rollback Trigger · Rollback Trigger	Which metric anomaly triggers rollback, who decides, time-to-rollback · Which metric anomaly triggers rollback, who decides, time-to-rollback
9	Upstream/Downstream · Upstream/Downstream	Synchronization requirements with other teams/services · Synchronization requirements with other teams/services
10	Compliance/Audit · Compliance/Audit	PII, GDPR, financial audit, operation log requirements · PII, GDPR, financial audit, operation log requirements

1.3 Risk Classification · Risk Classification

The classification result determines the downstream workflow routing: The classification result determines the downstream workflow routing:

Risk Level · Risk Level	Criteria · Criteria	Downstream Workflow · Downstream Workflow
🔴 Critical	Money flow / refunds / balance / state machine / distributed locks / cross-service MQ protocol / online schema migration · Money flow / refunds / balance / state machine / distributed locks / cross-service MQ protocol / online schema migration	→ `cross-verified-feature-development`(contains the full 9-phase superpowers sequence)
🟡 High	Estimated ≥ 3 person-days / multi-repo coordination / core order path changes · Estimated ≥ 3 person-days / multi-repo coordination / core order path changes	→ superpowers standard sequence:`brainstorming` → `writing-plans` → `test-driven-development` + `subagent-driven-development` → `systematic-debugging` → `verification-before-completion` → `requesting-code-review` → `receiving-code-review` → `finishing-a-development-branch`(if acceptance fails, return to writing-plans; if review finds major issues, return to debugging)
🟢 Standard	Pure new endpoints / no state machine semantics / single repo / < 3 person-days · Pure new endpoints / no state machine semantics / single repo / < 3 person-days	→ `direct`(user reads spec + tasks and implements directly · user reads spec + tasks and implements directly)

Phase 1 Output Format · Phase 1 Output Format:

我的初步判断（基于 PRD + Phase 1.0 调研：Lark 文档 + KB + 代码定向探针）
My initial assessment (based on PRD + Phase 1.0 research: Lark docs + KB + targeted codebase probe):
[每条用 "我假设 ..." 开头 · Each starts with "I assume ..."]

仍需你确认的 Open Questions · Still need your confirmation:
[只列 PM 清单中我无法自答的项 · Only list items I cannot self-answer from the PM checklist]

风险定级初判 · Initial risk classification: 🔴 Critical
[理由 · Reason: 触发 Phase 1.3 矩阵第 1 行（资金流 / 退款 / 余额）]
[考虑过的备选 · Alternatives considered: 🟡 High, but rejected because lacks cross-service contract change]

Recording "considered alternative classification + rejection reason" provides an audit trail for retrospective review. Recording "considered alternative classification + rejection reason" provides an audit trail for retrospective review.

Present the classification result and wait for user confirmation before proceeding. · Present the classification result and wait for user confirmation before proceeding.

1.4 Self-check before gate · Self-check before gate

Run automatically before presenting to user: Run automatically before presenting to user:

Used a specific Phase 1.3 risk level (🔴/🟡/🟢) and its criteria as the rationale
Considered at least 1 alternative classification with rejection reason
🔴 trigger keywords explicitly listed
All 10 PM checklist items answered or converted to Open Question

Any ❌ must be auto-fixed or explicitly acknowledged before proceeding.

Do NOT proceed to Phase 2 unless the user provides an explicit valid approval signal. Valid signals: "approve Phase 1" / "确认 Phase 1" / "Phase 1 OK, continue". Invalid signals (conversational acknowledgements, NOT approval): "looks good" / "continue" / "ok" / "好的" / "嗯" / "就这样".

Phase 2: Deep Codebase Scan

Phase 1.0 already completed targeted probes (to validate PRD assumptions). Phase 2's goal isfull impact surface mapping: find all affected files, interfaces, DB tables, and MQ topics, not just validate the PRD's core claims.

Phase 1.0 already ran targeted probes (PRD assumption validation). Phase 2 goal is comprehensive impact mapping: find all affected files, interfaces, DB tables, MQ topics — not just validating the PRD's core claims.

Before scanning, confirm repo paths (supplement any paths already gathered in Phase 1.0). Do not assume directory locations.

2.0 Confirm Repo Directories

Based on the affected services identified in Phase 1, ask the user (skip paths already confirmed in Phase 1.0):

我需要扫描以下仓库，请告诉我它们在你本地的路径：
I need to scan the following repos. Please tell me their local paths:

- <service-a>          → 路径 path？（例 e.g. ~/code/<service-a>）
- <service-b>          → 路径 path？（例 e.g. ~/code/<service-b>）
- <shared-contracts>   → 路径 path？（如有 proto 变更 · if proto changes needed）
（具体服务清单从你的 KB `repo-map.md` 中 Phase 1.1 已识别 · concrete service list comes from Phase 1.1's identification using your KB's `repo-map.md`）

如果多个仓库在同一个父目录下（例如都在 ~/code/），
If multiple repos share a parent directory (e.g. all under ~/code/),
告诉我父目录就够了，我会自动定位子目录。
just tell me the parent directory — I'll locate subdirectories automatically.

Start scanning only after the user confirms paths. If the user says "I'm not sure" or "find it yourself", use find ~ -name "go.mod" -maxdepth 5 to help locate them, but have the user confirm the results before scanning. find ~ -name "go.mod" -maxdepth 5 to help locate repos, but confirm results with the user before scanning.

2.1 Scan Priority

Tool Priority：

If an LSP service for the target language is available (such as Go's gopls, Python's pyright, TypeScript's typescript-language-server），preferusing the LSP's references / implementations / call hierarchy calls instead of grep — LSP can resolve symbol semantics, while grep easily misses interface implementation relationships. When LSP is unavailable, fall back to the grep + find combination below. If the current harness provides the LSP tool (such as Claude Code), call its references / implementations / call_hierarchy action; when unavailable, fall back to the grep + find below.

If target-language LSP is available (e.g. gopls for Go, pyright for Python, typescript-language-server for TypeScript), prefer LSP references / implementations / call hierarchy calls over grep — LSP resolves symbol semantics, while grep often misses interface-implementation relations. Fall back to the grep + find combo below if LSP is unavailable. If the current harness exposes an LSP tool (e.g. Claude Code), call its references / implementations / call_hierarchy actions; fall back to the grep + find block below if unavailable.

# 1. 找入口 handler（接口定义）· Find entry handlers (interface definitions)
grep -r "func.*Handler\|router\.\(GET\|POST\|PUT\)" <repo>/cmd/ --include="*.go" -l

# 2. 找受影响的 Service interface · Find affected Service interfaces
grep -r "type.*Service interface" <repo>/internal/ --include="*.go" -l

# 3. 找 DB 访问层（了解现有 schema）· Find DB access layer (understand existing schema)
grep -r "db\.WriteDB\|db\.ReadDB\|sqlx" <repo>/internal/ --include="*.go" -l

# 4. 找 MQ topics（跨服务消息）· Find MQ topics (cross-service messages)
# Find MQ topic registries. Seed pattern below — adapt the symbol name + path + file ext to your codebase.
grep -rE 'Topics\b|topic\.' <repo>/<your-mq-path>/ --include='*.go'

# 5. 找 proto 定义（跨服务接口契约）· Find proto definitions (cross-service contracts)
find <repo> -name "*.proto" | head -20

2.2 Scan Output

Produce animpact scope table(including a confidence column): Produce an affected scope table (with confidence column):

File	Impact	Change	Confidence
`<service-a>/internal/service/<domain>/<domain>_service.go`	modify	`CreateXxx()`: add feature flag branch	high high — directly named in PRD
`<service-a>/internal/<mq-path>/topic.go`	modify	MQ topic registry needs a new topic added in sync	Medium — pattern-matched from KB
`<shared-contracts-repo>/proto/<domain>.proto`	Modify?	Pending confirmation on whether a new field is needed	Low — needs user input
`<service-b>/internal/service/<domain>_v2/`	Add new consumer	new file required	High

confidence Three values:

High: directly named in the PRD, or an exact pattern match in the KB
Medium: inferred from a pattern, confirm again in the Phase 3 spec
Low: tentative assumption only, must become an Open Question

During the scan, if anyhidden riskis found (e.g., concurrent writes, no idempotency protection, backward-compatibility issues), flag it immediately with ⚠️ and include it in the Phase 3 invariants list. Any hidden risks discovered during scanning (e.g. concurrent writes, missing idempotency protection, backward compatibility issues) must be flagged immediately with ⚠️ and added to the Phase 3 invariants list.

2.3 KB Evolution Protocol

After the scan, for each service/pattern whereno corresponding mapping was found in the current KB, list a "candidate new KB entries" checklist:

After scanning, for each service/pattern not found in the currently loaded KB, list a "candidate new KB entry":

扫描发现以下新映射，KB 中尚无对应条目。要追加到 ~/.claude/prd-to-tasks/repo-map.md 吗？
Discovered the following new mappings; no corresponding entries in KB. Append to ~/.claude/prd-to-tasks/repo-map.md?

候选条目 · Candidate entries:
- "<requirement-signal>" → <service-name>  [user 确认 add / skip]
- "<another-signal>" → <another-service>   [user 确认 add / skip]

Rule：

The user mustexplicitly agreebefore writing (consistent with the HARD-GATE protocol)
This skill never writes silently to the KB · This skill never silently writes to KB
Show the full diff to the user before writing
Default write target is ~/.claude/prd-to-tasks/(user-level); if a project-level .claude/prd-to-tasks/ is detected and is more appropriate, ask which layer to write to

Phase 3: Spec Generation

Based on the ingested PRD + codebase scan results, generate a structured design document. Based on the ingested PRD + codebase scan results, generate a structured design document.

Default save path：docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md(rooted at CWD).

Downstream skills consume by fixed path (see Phase 5 routing hand-off contract). Downstream skills consume by fixed path (see Phase 5 routing hand-off contract).

Spec Template:

---
feature: <kebab-case-name>
prd-source: lark://docx/xxx 或 docs/prd/xxx.md 或 inline
risk-level: 🔴 Critical | 🟡 High | 🟢 Standard
affected-repos: [repo-a, repo-b]
spec-status: draft | approved | superseded   # HARD-GATE 通过后请手动将状态改为 approved · manually update to `approved` after HARD-GATE pass
created: YYYY-MM-DD
owner: <handle-or-email>
---

# Spec: <Feature Name>

## 业务目标 · Business Goal
[PRD 核心目标 + 验收标准 · PRD core objectives + acceptance criteria]

## 受影响的服务与仓库 · Affected Services & Repos
| 服务 Service | 仓库 Repo | 影响类型 Impact Type |
|-------------|----------|---------------------|

## 技术方案 · Technical Approach
[核心技术路径。每个关键决策点写明：选了什么，为什么不选备选方案
 Core technical path. For each key decision point: what was chosen, why alternatives were rejected]

## 边界 · Boundaries

### Always do · 必做（不需要再问 · no further confirmation needed）
- B-Always-1: ... (→ 技术方案 §X · backref to tech-approach decision)
- B-Always-2: ...

### Ask first · 先问再做（人在回路 · human-in-the-loop）
- B-AskFirst-1: ... (→ 技术方案 §X · backref to tech-approach decision)

### Never do · 严禁（红线 · red line）
- B-Never-1: ... (→ 技术方案 §X · backref to tech-approach decision)

> **Boundaries vs 不变式 · Boundaries vs Invariants**: Invariants = 系统/数据状态永远成立的命题（如"同一 booking_id 最多一次资金变动"）。Boundaries = agent 应执行/可执行/不可执行的**动作**。资金安全相关的命题可能两者都涉及——优先归入 Invariants（描述状态命题），Never-do 仅列对应的禁止动作。
>
> Invariants = propositions that always hold over system/data state. Boundaries = **actions** an agent should perform / may perform with human-in-the-loop / must not perform. Financially-sensitive items may touch both — prefer Invariants for the state proposition; Never-do should list only the forbidden corresponding action.

(每条带 ID，用于 Phase 4 task 反向引用 · Each entry has an ID for Phase 4 task back-references)

## API 契约变更 · API Contract Changes
[如有新增/修改接口 · If any new/modified interfaces]

## 数据模型变更 · Data Model Changes
[DB schema diff / proto field 变更 · DB schema diff / proto field changes]

## 不变式清单 · Invariants
- I-1: ... (→ 技术方案 §X · backref to tech-approach decision)
- I-2: ...
(每条带 ID，用于 task 反向引用 · Each entry has an ID for task back-references)

## 失败模式分析 · Failure Mode Analysis
[至少 4 种：正常路径崩溃 / 重试覆盖 / 并发竞态 / 下游超时
 At least 4: happy-path crash / retry idempotency / concurrent race / downstream timeout]

## 部署策略 · Deployment Strategy
[ ] 全量 Full rollout
[ ] Feature Flag（key: ___）
[ ] 灰度 Canary（比例 percentage: ___）
[ ] 双写切换 Dual-write switch

## 风险层级 · Risk Level
🔴 Critical / 🟡 High / 🟢 Standard（见 Phase 1.3 · see Phase 1.3）

## 回滚标准 · Rollback Criteria
[什么指标异常时触发回滚，谁来决定 · Which metric triggers rollback, who decides]

## 成功标准 · Success Criteria
[具体可测量的完成条件 · Specific measurable completion conditions]

## 遗留问题 · Open Questions

| # | 问题 Question | 影响 Impact | Owner | Deadline | 状态 Status |
|---|--------------|------------|-------|----------|------------|
| Q1 | ... | ... | @user | YYYY-MM-DD | open |

（状态 Status 枚举 · enum: `open` | `answered` | `deferred`）

3.1 Phase 3 self-check checklist before gate

After writing the spec, before showing to user, run automatically: After writing the spec, before showing to user, run automatically:

Placeholder scan: no "TBD" / "TODO" / "待确认" / "??"
Internal consistency: no contradictions among technical approach ↔ API contract ↔ data model
Scope consistency: Boundaries three sections ↔ JTBD + In/Not Doing/v2, no contradictions
Risk grading is consistent with the "Risk Levels" section description
Every Boundary / Invariant maps to at least 1 technical decision
Open Questions have no missing owners; no missing deadlines · Open Questions have owners + deadlines
Frontmatter complete: feature / prd-source / risk-level / affected-repos / spec-status / created / owner · Frontmatter complete (all 7 fields)

Any ❌ — auto-fix first; if unfixable, convert to a new Open Question for user. Any ❌ — auto-fix first; if unfixable, convert to a new Open Question for user.

Do NOT proceed to Phase 4 unless the user provides an explicit valid approval signal. Valid signals: "approve Phase 3" / "确认 Phase 3" / "Phase 3 OK, continue". Invalid signals: "looks good" / "continue" / "ok" / "好的" / "嗯" / "就这样".

Phase 4: Task Breakdown · Task Breakdown

After spec is confirmed, break down intoindependently executable, independently verifiableengineering tasks. After spec is confirmed, break down into independently executable, independently verifiable engineering tasks.

Default save path · Default save path：docs/superpowers/plans/YYYY-MM-DD-<feature>-tasks.md(rooted at CWD · rooted at CWD).

The top of the Plan file must carry machine-readable frontmatter (the actual carrier of the Phase 5 routing hand-off contract · the actual carrier of the Phase 5 routing hand-off contract).

4.0 Plan File Frontmatter · Plan File Frontmatter

The Plan file must begin with YAML frontmatter, which downstream skills use for routing:

---
feature: <kebab-case-name>
risk-level: 🔴 Critical | 🟡 High | 🟢 Standard
routed-to: cross-verified-feature-development | superpowers:writing-plans | direct
spec: ../specs/YYYY-MM-DD-<feature>-design.md
routed-rationale: |
  Selected <skill> because [...]
  Considered <alternative> but rejected: [...]
  Expected cost: [...]
plan-status: ready-for-execution
phase-gate-approvals:
  phase-1: { approved-at: "YYYY-MM-DD HH:MM", phrase: "approve Phase 1" }
  phase-3: { approved-at: "YYYY-MM-DD HH:MM", phrase: "确认 Phase 3" }
  phase-4: { approved-at: "YYYY-MM-DD HH:MM", phrase: "Phase 4 OK" }
created: YYYY-MM-DD
created-by: <handle-or-email>
---

Immediately after the frontmatter is thetask DAG（mermaid）： Immediately after frontmatter comes the task DAG (mermaid):

graph TD
  T1[Task 1: 修改 proto · modify proto] --> T2[Task 2: MQ topic 同步 · sync MQ topics]
  T1 --> T3[Task 3: consumer A]
  T2 --> T4[Task 4: consumer B]
  T3 --> T5[Task 5: 集成测试 · integration tests]
  T4 --> T5

The DAG lets users see the critical path and parallelizable batches at a glance, and is also the natural input for superpowers:subagent-driven-development . The DAG shows critical path + parallelizable batches at a glance, and is the natural input for superpowers:subagent-driven-development.

4.1 Task Format · Task Format

Each task must include: Each task must include:

### Task N: <动词 + 宾语 · verb + object>

**仓库 Repo**: <service-name>
**文件 File**: `path/to/file.ext`（如修改现有文件带行号 · with line range if modifying existing file）
**类型 Type**: 新增 add / 修改 modify / 删除 delete / 契约变更 contract change
**尺寸 Size**: XS / S / M / L / XL
**拆分被否决的理由 · Split rejection reason** (XL only): <reason — required if Size=XL>
**spec-refs**:
  - section: "技术方案 · Technical Approach"   # 引用 spec h2 节标题（原文复制 · copy heading text verbatim）
  - boundary: B-Always-1                       # 可多条 · multiple OK
  - boundary: B-AskFirst-1                     # 触发人工确认的边界
  - boundary: B-Never-2
  - invariant: I-3                             # 可多条 · multiple OK

**具体改动 · Specific Changes**:
[用代码片段说明，不用散文描述 · Use code snippets, not prose]

**关联代码模式 · Associated Code Patterns** (见 KB `~/.claude/prd-to-tasks/service-patterns.md`)：
- [ ] [按 KB 引用具体 pattern · cite specific patterns from KB]

**验证命令 · Verification Commands**:
\`\`\`bash
<project-specific build/test/lint commands>
\`\`\`

**依赖 Dependencies**: Task X, Task Y
**风险标注 Risk Notes**: ⚠️ ... （如有 · if any）

4.1.1 Size Scale · Size Scale

Label	Time	When to use
XS	< 30 min	Single file, < 20 lines changed, no new logic · Single file, < 20 lines, no new logic
S	30 min – 2h	Single file, < 100 lines · Single file, < 100 lines
M	2 – 4h	Single service + tests · Single service + tests
L	4 – 8h	Multi-file coordination · Multi-file coordination
XL	> 8h	Should be split further · Should be split further; if kept, must include "split rejection reason" · If kept, must include "split rejection reason"

4.2 Task Ordering Principles · Task Ordering Principles

Contract First · Contract First: tasks that modify proto / shared-models go first (other repos depend on them) Tasks that modify proto / shared-models go first (other repos depend on them)
DB Schema First · DB Schema First: online DDL before logic implementation Online DDL before logic implementation
Within a single repo · Within a single repo: interface definition first, then implementation, finally consumer Interface definition → implementation → consumer
Tests alongside implementation · Tests alongside implementation: each task includes corresponding test tasks in the same batch Each task includes corresponding test tasks in the same batch

4.3 Phase 4 completeness self-check · Completeness self-check before gate

Before showing the task list to user, run automatically:

Every spec Boundary/Invariant referenced by ≥1 task spec-refs · Every spec Boundary/Invariant referenced by ≥1 task
Each Failure Mode has a corresponding test task · Each Failure Mode has a corresponding test task
proto / shared contracts modification tasks ordered before all consumer tasks · Contract-first task ordering
online DDL / schema migration tasks ordered before all logic tasks · DB-schema-first ordering
No unsplit XL (or explicit rejection reason) · No unsplit XL (or explicit rejection reason)
Every task has executable build/test verify commands · Every task has executable build/test verify commands
Plan frontmatter routed-to / spec / phase-gate-approvals Plan frontmatter complete · Plan frontmatter complete
In the task listdoes not containcompany-internal helper / internal topic / internal layout naming (open-source safety check) · No company-internal identifiers leaked (open-source safety check)

Any ❌ must be fixed or explicitly acknowledged before entering Phase 5. Any ❌ — fix or explicitly acknowledge before entering Phase 5.

Do NOT proceed to Phase 5 unless the user provides an explicit valid approval signal. Valid signals: "approve Phase 4" / "确认 Phase 4" / "Phase 4 OK, continue". Invalid signals: "looks good" / "continue" / "ok" / "好的" / "嗯" / "就这样".

Phase 5: Workflow Routing · Workflow Routing

After the task list is confirmed, based on the risk level from Phase 1.3write into the plan file's frontmatter routed-to: field——routing is no longer a verbal deliverable, but a machine-readable contract.

After the task list is approved, based on Phase 1.3 risk classification, write the decision into the plan file's frontmatter routed-to: field — routing is no longer a verbal hand-off but a machine-readable contract.

5.1 Routing Decision Tree · Routing Decision Tree

风险层级 · Risk level = ?
│
├── 🔴 Critical → routed-to: cross-verified-feature-development
│                  完整 9 阶段 superpowers 序列（含 4 轮交叉验证）
│                  预期额外成本 · expected cost premium: +40–50% time
│
├── 🟡 High → routed-to: superpowers 标准序列（7 步）
│
│   ① superpowers:brainstorming          （如 spec 已够完整可跳过）
│   ② superpowers:writing-plans          （spec + task 清单作为输入）
│   ③ superpowers:test-driven-development
│      + superpowers:subagent-driven-development     （测试先行 + 按计划实施）
│   ④ superpowers:systematic-debugging   （实施后自查）
│   ⑤ superpowers:verification-before-completion
│      ↩ 验收不通过 → 回 ② writing-plans 重新规划
│   ⑥ superpowers:requesting-code-review
│      → superpowers:receiving-code-review
│      ↩ 重大问题 → 回 ④ systematic-debugging + 修复
│   ⑦ superpowers:finishing-a-development-branch
│
└── 🟢 Standard → routed-to: direct
                   用户直接读 spec + 任务清单实施 · user reads spec + tasks and implements directly

5.2 Downstream Consumption Contract · Downstream Consumption Contract

Downstream skill · Downstream	How it reads the plan header · How it reads the plan header
`cross-verified-feature-development`	Verify `routed-to == self`, read `spec:` file as Phase 1 input, task list as Phase 2 input · Verify `routed-to == self`, read `spec:` file as Phase 1 input, task list as Phase 2 input
superpowers standard sequence (🟡 High)	Read `spec:` + task list as input, call in order:`writing-plans` → `test-driven-development` + `subagent-driven-development` → `systematic-debugging` → `verification-before-completion` → `requesting-code-review` → `receiving-code-review` → `finishing-a-development-branch`
`direct`	N/A — no downstream skill. User manually reads spec + task list and implements directly · N/A — no downstream skill. User reads spec + tasks and implements directly

5.3 Phase 5 Output · Phase 5 Output

This skill does not automatically invoke downstream——it only outputs suggested commands. For example:

This skill does NOT auto-invoke downstream — it only outputs suggested commands. For example:

✅ 路由完成 · Routing complete.

Spec:  docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md
Plan:  docs/superpowers/plans/YYYY-MM-DD-<feature>-tasks.md
Routed-to: cross-verified-feature-development   # 或 superpowers 标准序列

── 如果 🔴 Critical ──
建议下一步（请在新会话中运行）· Suggested next step (run in a new session):
  /cross-verified-workflow

── 如果 🟡 High ──
建议按顺序调用（每步完成后再调用下一个）· Call in sequence:
  1. /superpowers:writing-plans          （读 spec + 任务清单，产出实施计划）
  2. /superpowers:test-driven-development + /superpowers:subagent-driven-development  （测试先行 + 实施）
  3. /superpowers:systematic-debugging   （自查）
  4. /superpowers:verification-before-completion  （验收；不通过回 step 1）
  5. /superpowers:requesting-code-review → /superpowers:receiving-code-review  （重大问题回 step 3）
  6. /superpowers:finishing-a-development-branch  （收尾）

Reason · Reason: cross-phase transition is a natural review point; auto-invoking would remove the user's last chance to change their mind. Cross-phase transition is a natural review point; auto-invoking removes the user's last veto window.

Common Rationalization Excuses · Common Rationalization Excuses

Excuse · Excuse	Reality · Reality
"The requirement is simple, let's just write code" · "The requirement is simple, let's just write code"	Simple requirements still need affected service confirmation — the "simpler" a change seems, the more likely cross-service impact is missed
"Code scanning wastes time, I know where to make changes"	The point of scanning is to find dependencies and risks youdon't know about, not to find files you already know about don't know about, not to locate files you already know
"Start on tasks first, write the spec later"	The value of a spec is exposing design flawsbefore writing code; what you add afterward is documentation, not a spec before writing code — writing it afterward produces documentation, not a spec
"Risk isn't high, don't need cross-verified"	The value of cross-verified comes from independent perspective, not from the developer's own risk assessment
"No need to check Lark docs, PRD is self-contained"	PRDs typically omit design rationale and historical constraints; related tech docs and predecessor PRDs document critical restrictions. Skipping means reasoning from assumptions instead of evidence
"Defer code research to Phase 2"	Phase 1 risk classification without code evidence is blind; Phase 1.0 targeted probes take minutes and cost far less than rework caused by mis-classification

Reference Files

File	When to Read
`references/repo-map.md`	Phase 1: identifying affected services
`references/service-patterns.md`	Phase 4: breaking down tasks, checking associated code patterns