plan-report

Framework Plan Report Assistant

Function Description

Help users produce aframework plan report—a document type positioned between the "project charter" and the "detailed design."

It answers:Why do it / what counts as done / who uses it / what not to do / how many steps to take / what business questions can be asked at each stopping point。

Itdoes not answer: fields, interfaces, tech stack, directory naming, cron expressions—these are matters for the subsequent "detailed design document."

Core value:Turn the plan report into a story readers can understand, rather than a work checklist the author uses to confirm scope with themselves. Through 7 guided steps, align with the user on direction, skeleton, and content, and only then write it down.

Core Principles

1. Gather evidence before designing

Do not speculate out of thin air. First understand the current situation clearly—run what can be run, read the code that can be read, list the known constraints.

Signal: Be able to answer "what is the current situation / what can be obtained / what hard constraints exist / who will consume this document." If you cannot answer these four questions, do not enter Stage 2.

2. Document type determines everything

When you receive a request, the first thingis not to start writing, but to ask yourself: what type of document is this?

Type	Core question	Writing characteristics
Project charter	Why initiate the project	Strategic, 1-2 pages
Framework plan(this skill)	Why do it / how many steps	No fields involved, talk up to phase acceptance
Business description	What capabilities are provided externally	Functional perspective, easy to list more and more
Detailed design	How to implement	Fields / interfaces / tech stack all complete
PRD	User stories / acceptance	User perspective, requirements turned into scenarios

Cost of mismatch: Writing a framework plan as a business description → it becomes a feature list; writing it as a detailed design → you get stuck in field details.Type misplacement discounts all subsequent efforts。

3. State descriptions > action descriptions

Both the overall goal and acceptance use the "can X" sentence pattern—"data can come in stably," "the customer list is available," "failures can be detected."

Why: State descriptions are themselves acceptance criteria; action descriptions are merely process language. "Data can come in stably" clarifies the definition of done, while "collect data" only describes the workload.

4. Split versions, do not pile up features

Each version solves only one main problem. Do not list "a pile of features X / Y / Z"—it looks complete but cannot actually be advanced, and easily becomes a bottomless pit.

Counterexample: "v1.0 includes Metabase / Grafana / SQLite / API / alerts / backup / model merging / customer list" Example: "v0.1 the foundation can run / v0.2 the main business metrics come in / v0.3 the monitoring perspective is completed / v0.4 upper-layer business can use it"

5. Work backward from acceptance to delivery

For each stagefirst ask "what counts as this stage being complete", then work backward from acceptance to what should be delivered. Do not first ask "which modules need to be built".

Acceptance is best phrased as "the system can already answer X / Y / Z"—this naturally connects technical acceptance with business value.

6. Non-goals must come with reasons

"Not doing" cannot just be listed. Each item must come with "why it is not included in this version".

Why: the key weapon against scope creep. When the business side questions "why aren't we doing X", you can point directly to the reason on this line—otherwise the discussion will be reopened again and again.

7. Always serve the reader

The implicit question of the entire document is:

A personwho has never been exposed to this project at all, after reading it, can they understand why the project is viable, what level of completion counts as done, and whether it is useful to them?

Forbidden: writing content in the framework plan that is "for ourselves to confirm the scope"—the table of contents skeleton, technology stack selection, field details, concurrency model; these are all matters for the detailed design stage.

Workflow

Stage 1: Grasp reality

Goal: clarify the current situation before writing, so that all later design judgments can point back to facts.

Step 0: Quick scale screening (do this before entering Stage 1 to prevent misuse on small projects)

Before entering Stage 1first ask two yes/no questions, and if both answers trigger "small",exit the skill directly, do not continue—this scenario should not use plan-report:

Estimated duration: < 1 week / 1 week - 6 weeks / > 6 weeks?
How many independently deliverable stages can be broken out: 1 / 2-3 / 4+?

Exit rules:

Estimated < 1 week and only 1 stage can be broken out → explicit exit: "This scenario does not need a framework plan; it is recommended to switch to a 1-page 'what to do + how to verify' document"
Estimated 1-6 weeks + 2-3 stages broken out → usesmall project skeleton(8-9 sections, see the "Templates" section)
Estimated > 6 weeks / 4+ stages broken out → usestandard skeleton(10 sections)

If you do not do quick scale screening → AI will force the standard skeleton onto small projects, causing over-structuring.This step is a hard constraint of this skill improvement and cannot be skipped。

Step 1: Collect the following information (fill in what is known, mark what is unknown as to be supplemented)

Project background: project name, current stage (initiation / in progress / transformation) / whether there is an upper-level architecture baseline
Current situation: existing code / what the existing system can run to / what data can be obtained / what the output form is
Target consumers: who this plan is for / who will act based on it
Hard constraints: technical constraints (API rate limits, data windows, storage limits), business constraints (scale, pace, budget), organizational constraints (who is responsible, when to launch)

Follow-up question template:

"What part can run through now? Can you run it so I can see the real output?"
"Is there any upper-level document (architecture baseline, project initiation document, research report) that I should read first?"
"Who is this plan for—internal product and engineering / cross-team / customer?"
"Are there any known hard constraints? For example, API rate limits, launch deadlines, customer volume caps?"

Step 2: Hard gate + information depth self-check

Hard gate:

Do not enter Stage 2 unless you can answer in 3 lines "what the current state is / what can be obtained / what hard constraints exist / who will consume it"
Designing out of thin air is the easiest pitfall to fall into with this skill—starting to write without grasping reality = all subsequent judgments have no foundation

Information depth self-check(to prevent Stage 1 from being fooled by vague answers):

In the current-state answer,there must be specific numbers / system names / data scale(for example "50+ business lines", "12 bash scripts", "20 million customers"); only adjectives ("quite a lot", "not a few") do not count as passing the gate
In the hard-constraint answer,there must be specific values / time limits / interface limits(for example "Feishu API 100 QPS", "Hive query 10-30 seconds"); "I heard there are limits" does not count as passing the gate
If the answers are all vague adjectives,return to the follow-up question template and ask through each item, do not force your way through the gate

Gray channel for the pre-project initiation stage: if the project is truly at the early initiation stage and the user reallydoes not yet have precise numbers, you may use "order-of-magnitude estimates + 1-2 specific pain-point scenarios" instead of precise numbers (for example "dozens of business lines" + "last time a team misconfigured an alert and it was only discovered 3 months later"). But only for early initiation—projects already underway must provide specific numbers。

Step 3: The "stuck output format" when information is incomplete

If the hard gate is not passed (information is insufficient to enter Stage 2),do not force out a plan. At this point the correct output is a **"stuck-state explanation"**, with the fixed format as follows:

# {项目名} v1.0 计划 — Stage 1 卡住,待补信息

## 已收集信息

- 项目背景: {已知部分 / 待补}
- 现状: {已知部分 / 待补}
- 目标消费方: {已知部分 / 待补}
- 硬约束: {已知部分 / 待补}

## 还需要从用户追问的 X 个具体问题

1. {具体问题 1,例如"现在文档散在哪些系统里?多少篇?"}
2. {具体问题 2,例如"使用人数 30 / 300 / 3000?"}
3. {具体问题 3,例如"最近一次'用起来不爽'的具体场景是什么?"}
...

## 进 Stage 2 的最低标准

收到上面问题的回答后,要保证能用 3 行话回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费"。

Prohibited: starting with "As I understand it, you probably want to do X" / "I assume your current state is Y" and forcing a fill-in. This is a disguise for filling in out of thin air, equivalent to forcing through Stage 1.

Stage 2: Determine the document type

Goal: confirm that what is to be written is a "framework plan", not another type; if it is another type, prompt the user to switch skills.

Key actions:

Align with the user on the positioning of this document:

Itanswers: why do it / what level of completion counts as done / who uses it / what not to do / how many steps / acceptance for each step
Itdoes not answer: fields, interfaces, tech stack, directories, cron expressions, concurrency models

If the user says "I want to write all the fields clearly"—this is detailed design, this skill does not apply, and it is recommended to create a separate document.

If the user says "I want to list the features we can provide"—this is a business description, this skill does not apply, and it is recommended to create a separate document.

Follow-up question template:

"Who is this document mainly for? For the people doing the work → detailed design; for the people understanding the work → framework plan"
"What problem do you expect it to solve?—'getting the team aligned on what to do / how to count as done' is a framework plan; 'letting the business side know what can be used' is a business description"

Hard gate:

Before the document type is clear, do not build the skeleton
Misplaced types = the entire document is invalid; this step must be blocked

Stage 3: Build the skeleton

Goal: Finalize the fixed skeleton of the framework plan and have the user verify it.

Fixed skeleton of the framework plan (5 sections):

定位 → 痛点 → 边界 → 阶段 → 验收

Expand into chapters (standard version, 10 sections):

1. 项目定位          (是什么 / 不是什么)
2. 为什么要做         (核心痛点)
3. 服务/系统边界      (负责 / 不负责)
4. v1.0 总体目标      (做到什么程度算完)
5. 版本路线           (分几步,只一行流程图)
6. v0.1 阶段          (要解决的问题 / 主要交付 / 阶段验收)
7. v0.2 阶段          (同上三段式)
8. v0.3 阶段          (同上三段式)
9. v0.4 阶段          (同上三段式)
10. v1.0 之后再考虑   (后续不做,每条配理由)
11. (可选) 关联文档——如果上层文档全部为空,**整节删除**,不要留"待补"占位符

Project scale adaptation(Critical, to avoid over-structuring small projects):

Project scale	Number of stages	Number of overall goal lines	Number of pain point table rows	Total number of sections
Small (1 person < 6 weeks / < 2 person-months)	2-3	3-4 lines	3-4 lines	8-9 sections
Medium (1-3 people, 1-3 months)	3-4	4-5 lines	4-5 lines	9-10 sections
Large (>3 months / multi-person collaboration)	4-5	5-6 lines	5-7 lines	10-11 sections

Core discipline:Set the number of lines based on the real situation; do not pad numbers to match template defaults. Readers can spot padded content at a glance.

Each stage must use a unified three-part structure, regardless of project scale—this point does not change.

Key operational points:

Skeleton firstpresent the whole thing to the user, and let them add/remove chapters and adjust the order
Prohibited: changing the skeleton while writing
Prohibited: starting to fill in content before the user confirms

Follow-up template:

"Is this skeleton right? Are there any chapters to add / remove / reorder?"
"How many stages should there be?—Work backward from 'each stage solves one main problem'; usually 3-5 is appropriate"

Hard gate: Skeleton not confirmed → do not proceed to Stage 4.

Stage 4: Fill in each section (according to the 4 principles)

Goal: Fill in content section by section, with each section written according to the "4 principles of content judgment."

4 principles:

Principle 1: First define what it is / is not

Open with the sentence pattern "Its goal is not X, but Z". First rule out common misunderstandings, then establish the correct positioning.

The number of misunderstandings depends on the scenario: 1-3,better to have fewer than to pad. If you cannot think of a second real misunderstanding,do not force one in—readers can spot forced misunderstandings at a glance.

Special note for internal tool projects: If the project is a tool for an internal team (alerting platform, inspection tool, CI platform, etc.), readers may not have the misunderstanding of "thinking it is X"—in that case,switch to a contrastive form: "it does X / does not do Y," rather than forcibly writing "not A / not B / not C."

Why: Readers often come with wrong expectations (thinking it is a "data platform," "business system," or "analytics tool"). Only by first eliminating misunderstandings can the positioning hold.But if a misunderstanding does not exist, do not invent one。

Principle 2: Find the pain points; do not say "we want to do X"

Section 2, "Why do it," uses the "Problem | Impact" table——Each line is a noun phrase + one specific consequence.

The number of lines should match the real pain points; don't pad it.:

Small projects (<6 weeks / <2 person-months): 3-4 lines is usually enough
Medium projects: 4-5 lines
Large projects: 5-7 lines
Pain point screening criteria (3-second judgment method):Can this pain point be called out in a production incident postmortem / business stakeholder complaints? If yes → keep it; if no → delete it.

Counterexample:P1. 多个业务重复抓数据 Good example:重复采集 | 日报、客户分析、价值评估都各自拉一遍,浪费维护成本

Principle 3: Split versions, don't pile up features

Section 5 "Version Roadmap"Include only one flowchart, without explanation.

v0.1 底座能跑 → v0.2 业务主口径进来 → v0.3 监控视角补齐 → v0.4 上层业务能用 → v1.0 正式可用

Each version solves only one main problem. If a version needs to solve 3 things, it usually means it wasn't split enough.

Principle 4: Use acceptance to reverse-engineer delivery

For each stage, write "stage acceptance" before "main deliverables". Work backward from acceptance to determine what to deliver, rather than forward from the feature list to acceptance.

Follow-up question template:

"If this section were applied to a different project, would it still hold? If it holds, it means you're writing empty words and need to rewrite it more specifically"
"Is this pain point really painful, or is it a pain we imagined? Can the business side perceive it?"
"Can this version be split further? If one version has to do three different things A B C at the same time, it may not be split enough"
"Is this acceptance a technical metric or a question the business can ask?"

Hard gate:After writing each section, have the user take a look and confirm the direction is right before continuing—avoid laying out the whole document only to discover the direction is off.

Stage 5: Use a unified three-part structure for each version

Goal:Each version (v0.1 / v0.2 / ...) is expanded using the same three-part structure.

Three-part structure:

### v0.X {阶段标题}:{一句话主线}

**要解决的问题**

{2-3 句,说清楚这个阶段为什么存在 / 不做会怎样}

**主要交付**

- {交付物 1}
- {交付物 2}
- {交付物 3,不超过 5-6 个}

**阶段验收**

{按项目类型选一种句式}

3 alternative sentence patterns for stage acceptance(choose the most suitable one, don't force the data query type):

Project type	Acceptance sentence pattern	Example
Data / query type	"The system can already answer X / Y / Z"	"How many calls did a certain customer make on a certain day / how many Tokens were consumed / what is the main model distribution"
Tool / process type(dashboard, collection, automation)	"X can do / Y can do" status checklist	"A newcomer can look at the dashboard to judge system status without reading the source code / any one of the 6 SREs can run all inspections with one click"
Platform / service type	Three parts: capability statement + customer-observable signal + fallback	"The API can stably receive alerts / the business side can confirm within 30 seconds whether it was sent / the old link is retained without forced cutover"

ProhibitedForcing tool-type acceptance into "the system can answer X"—this will produce grammatically awkward sentences like "the system can answer 'whether a newcomer can get started'".Sentence patterns should serve the scenario, not the scenario serve the sentence pattern。

Why unification is necessary:

Readers can compare stages horizontally at a glance (what problems v0.1 vs v0.2 solve, what they deliver, and what their acceptance is)
It is less likely to become a running account
It won't fall into technical implementation too early
The weight of each stage looks "equivalent"; one stage won't be written in especially great detail while another is especially perfunctory

Prohibited:

v0.1 uses "what to do / value", v0.2 uses "goal / deliverable", v0.3 invents its own format again
Add extra subsections to a certain stage (such as "risks", "dependencies"), unless you add them to every stage

Follow-up template:

"Try every stage's acceptance criteria with the 'the system can answer X' sentence pattern, and see if it reads smoothly"
"This deliverable list has more than 6 items. Should we cut it down? Or explain that this stage is not broken down finely enough"

Stage 6: Language refinement

Goal: After finishing the draft, scan each section according to the 5 replacement phrasings.

5 replacements:

Don't write it like this	Change it to this	Why
Action description ("collect data")	State description ("data can come in stably")	The state itself is the acceptance criterion
Technical acceptance ("field alignment")	Business question ("the system can already answer X / Y / Z")	Connect technical acceptance with business value
Non-goals only say "won't do X"	Non-goal + "why it isn't included in the current version"	Prevent scope creep
Pain points use P1/P2 numbering + long sentences	Pain points use noun phrases + one specific consequence	Concise and powerful
Titles pile on modifiers ("v1.0 positioning and boundary scope description")	Plain title ("Project positioning")	Use fewer modifiers; the shorter the title, the better

Follow-up template:

"Does this passage read like 'I'm explaining something to you' or 'I'm listing the things we need to do'? If it's the latter, it needs to be changed"
"If this bullet is changed to a state description of 'X can Y', can it still be clear?"

Stage 7: Self-check + save to disk

Goal: After writing, do a "reader's perspective self-check"; only save to disk after passing it.

Self-check list(mandatory item-by-item check):

Core question: After an unfamiliar reader finishes reading, can they understand "why the project exists / what counts as done / whether it is useful to them"?
Type purity: Has the document mixed in fields, interfaces, tech stacks, directory naming, cron expressions? If yes → delete
Pain point authenticity: Is every pain point perceivable by the business side? Or does it just feel like the author thinks "it should be mentioned"? Use the 3-second judgment method: can it be called out in an incident retrospective / business-side complaint
Version splittability: Does each version solve only one main problem? If a version does A B C at the same time, either split it or merge it into the next version
Three-part discipline: Do all stages strictly use the three parts "problem to solve / main deliverable / stage acceptance"? Is there any stage that invents its own format?
State description: Are the overall goal and acceptance criteria all in the "can X" sentence pattern? Or have action descriptions been mixed in?
Non-goals paired with reasons: Does every "won't do" in Section 10 have a sentence "why it isn't included in the current version"?
Business question: Do the acceptance criteria include the sentence pattern "the system can already answer X / Y / Z"?
Unified naming: Does the whole text call it "v1.0", "Phase 1", "first version" — use one, don't mix them
Boundary vs. Not Doing Deduplication(Added): Do Section 3 "Not Responsible For" and Section 10 "Consider After v1.0" have semantic confusion?—The former is "never do" (responsibility boundary), while the latter is "not in this version but may be done later" (scope boundary)
Turning Technical Constraints into Business Language(Added): Are the project's hard constraints (API rate limits, data windows, compliance, etc.) written in business language under "Problems to Solve," rather than thrown out as technical details?
Reverse Check for Over-Structuring(Added): For every table / every phase, ask "If this row / this phase is cut, does the document still hold? If it holds, cut it."
No Padding by Line Count(Added): For the line counts of the overall goals / pain point table / not-doing items, is there anything "forced in just to pad the count"?—If a line is especially vague or especially like "going through the motions," delete it

Write to Disk:

Default path:docs/plan/{版本号}-{命题}-{项目名}.md, e.g. docs/plan/v1.0-框架-customer-metrics-service.md
Also generate HTML (using this skill's md → html tool, see the end)

Prohibited: Writing to disk if self-check has not passed—once submitted, the business side will understand it according to the misaligned version, and the cost of later correction is high.

Templates

Two Sets of Templates: Which set to use after the Stage 1 scale quick screening—

Small project (1-6 weeks / 2-3 phases) → usesmall project skeleton(8-9 sections)
Medium-to-large project (>6 weeks / 4+ phases) → usestandard skeleton(10 sections)

Small Project Skeleton (8-9 Sections)

Applicable: 1 person, 1-6 weeks / tool type / single-team internal use / cannot be independently delivered without splitting into multiple phases.

# {项目名} {版本} 框架计划

> 状态:框架计划版
> 日期:{YYYY-MM-DD}
> 项目规模:小(1 人 X 周 / Y 阶段)

---

## 1. 项目定位

{项目名} 是一个 **{核心定位 1 句话}**。

**它做**:{X 件具体能做的事,3 行内}
**它不做**:{Y 件明确不做的事,2 行内,跟"v1.0 之后"区别开}

> 内部工具类项目:用"它做 / 它不做"对照式,不强求"不是 A / B / C"误解

---

## 2. 为什么要做

| 问题 | 影响 |
|---|---|
| {真实痛点 1} | {具体后果} |
| {真实痛点 2} | {具体后果} |
| {真实痛点 3} | {具体后果,3-4 行够,不凑数} |

---

## 3. {版本} 总体目标

| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式} | {说明} |
| {状态 2} | {说明} |
| {状态 3,3-4 行够} | {说明} |

---

## 4. 版本路线

```text
v0.1 {阶段口号} → v0.2 {阶段口号} → v0.3 {阶段口号} → {版本} 可用
```

---

## 5. v0.1 {标题}

### 要解决的问题
{...}

### 主要交付
- {...}

### 阶段验收
{用工具型 / 平台型句式,见 Stage 5 三段式备选}

---

## 6. v0.2 {标题}
(同上三段式)

## 7. v0.3 {标题}
(同上三段式)

---

## 8. {版本} 之后再考虑什么

| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由} |
| {不做项 2} | {理由,2-3 行够} |

Core Constraints of the Small Project Skeleton(differences from the standard skeleton):

No Section 3 "Service Boundary"—melted into Section 1 "What It Does / What It Does Not Do"
No "Related Documents" section—small projects usually have no upper-level documents
Overall goals 3-4 lines(not 6 lines)
Pain points 3-4 lines(not 5 lines)
2-3 phases(not 4)

Standard Skeleton (10 Sections)

Applicable: 1 person >6 weeks / multi-person collaboration / 4+ phases / cross-team consumption / has an upper-level architecture baseline.

# {项目名} {版本} 框架计划

> 状态:框架计划版,技术细节留待详细设计阶段
> 日期:{YYYY-MM-DD}
> 上层文档:{架构基线 / 立项书 路径,如有}

---

## 1. 项目定位

{项目名} 是一个 **{核心定位 1 句话}**。

它的目标**不是** {常见误解 1} {/ 误解 2 / 误解 3 — 按真实情况,1-3 个,宁缺勿凑},**而是** {正确定位}。

> **如果是内部工具类项目**且想不出真实误解,改用对照式:"它做 X / 不做 Y",不要硬凑误解。

一句话概括:

```text
{核心动作链路,如:统一采集 → 统一沉淀 → 统一口径 → 统一接口 → 给上层业务使用}
```

---

## 2. 为什么要做

现在 {一句话现状}。这样会带来几个长期问题:

| 问题 | 影响 |
|---|---|
| {痛点 1} | {具体后果 1} |
| {痛点 2} | {具体后果 2} |
| {痛点 3} | {具体后果 3} |
| ... | ... |

> **行数按真实痛点数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-7 行。**3 秒判断法**:这条痛点能不能在生产事故复盘 / 业务方吐槽里被点名?能 → 留;不能 → 删。

{版本} 要解决的是这些基础问题,而不是一次性把所有 {业务/能力} 都做完。

---

## 3. 服务边界

{项目名} 只负责 **{核心职责}**。

```text
{上游 / 输入}
   ↓
{本项目}   ← 当前文档
   ↓
{下游 / 消费方}
```

本项目负责:

- {职责 1}
- {职责 2}
- {职责 3}

本项目不负责:

- {不做 1}
- {不做 2}
- {不做 3}

这些能力属于 {归属方}。

---

## 4. {版本} 总体目标

{版本} 的目标是做出 {状态描述},而不是 {容易被误解的更大目标}。

| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式,如"数据能稳定进来"} | {1 句说明} |
| {状态 2} | {1 句说明} |
| {状态 3} | {1 句说明} |
| ... | ... |

> **行数按真实状态数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-6 行。
> **"老链路可兜底"是 customer-metrics-service 这个示例项目的具体一行(因为有 maas_bot 老链路)——不要把它当成模板必填项。新项目如果没有"老链路",这一行就不要有。**

{版本} 不追求 {显式排除的过度目标},只要 {核心目标} 即可。

---

## 5. 版本路线

{版本} 拆成 N 个内部阶段推进。每个阶段只解决一个主问题。

```text
v0.1 {阶段口号}
  ↓
v0.2 {阶段口号}
  ↓
v0.3 {阶段口号}
  ↓
v0.4 {阶段口号}
  ↓
{版本} 正式可用
```

---

## 6. v0.1 {阶段标题}:{一句话主线}

### 要解决的问题

{为什么需要这个阶段 / 不做会怎样}

### 主要交付

- {交付物 1}
- {交付物 2}
- {交付物 3}

### 阶段验收

{1-2 句状态描述 + "系统已经可以回答 X" 句式}

---

## 7. v0.2 {阶段标题}:{一句话主线}

### 要解决的问题

...

### 主要交付

...

### 阶段验收

这一阶段结束后,系统已经可以回答:

- {业务问句 1}
- {业务问句 2}
- {业务问句 3}

---

## 8. v0.3 ...

...

---

## 9. v0.4 ...

...

---

## 10. {版本} 之后再考虑什么

{版本} 只解决 "{核心目标}"。以下事项不放进 {版本} 主目标:

| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由 1} |
| {不做项 2} | {理由 2} |
| {不做项 3} | {理由 3} |

{版本} 的核心原则是:

```text
{一句话原则,如"先把数据底座跑稳,再扩展计算和产品能力"}
```

---

## 关联文档

- 上层文档:{路径}
- 项目记忆:{路径}
- 旧代码参照:{路径}

Key Constraints:

All phases (v0.1-v0.4) must use a unified three-part structure; do not add extra subsections to any phase
No field names, table names, interface paths, tech stacks, directory paths, or cron expressions
Not-doing items must have a "Why Not in the Current Version" column
Titles plain, no piled-on embellishment

Example Reference

Actual case (customer-metrics-service v1.0)

File path:docs/plan/v1.0-框架-customer-metrics-service.md

Key Design Decisions:

Project positioning first uses "not X / Y / Z, but Z" to eliminate misunderstandings—"not doing customer value scoring, ROI analysis, or daily report pages, but unifying scattered data into one collection point"
Section 4 overall goals use 6 lines of the "can X" sentence pattern—data can come in stably / can settle stably / definitions can be unified / can be read by programs / failures can be discovered / the old pipeline can fall back
All 4 stages use a unified three-part structure, and acceptance uses the sentence pattern "the system can already answer X / Y / Z"
Section 10's not-doing items use a "future direction | why it is not included in v1.0" table, with a reason for each item
Finally, close with a slogan: "first get the data foundation running steadily, then expand computing and product capabilities"

6 anti-patterns AI often falls into when writing planning reports(if you see yourself writing any of the following, stop and rethink):

Splitting versions by "input resources"(data source / customer type / third-party dependency) → should split bycapability layer(foundation → business integration → service exposure). Ask yourself: can each version independently deliver a "capability the user can perceive"? If not → the split is wrong.
Cramming "business computation / upper-layer processing" into your own service boundary → should make it clear that "I only go up to the factual data layer; business computation belongs to an independent module." Ask yourself: if this responsibility is cut, does my service still hold? If it holds, it should be cut.
Over-designing for the maximum future scale(concurrency pool / queue / aggregated alerts / multi-tenancy) → should design for thereal scale of the current 1.0, leaving interfaces without implementing them. Ask yourself: is this complexity truly needed by v1.0, or is it "what if there are 100x users"?
Writing technical details (directory skeleton / Docker / tech stack / cron expressions / fields) into the framework plan → should all be pulled out and left for the "detailed design document." Ask yourself: if this section were implemented with a different tech stack, would it still hold? If it holds → it is business, not technology, keep it; if not → delete it.
Writing the "framework plan" as a "business capability list"(listing "provides X / Y / Z features") → shouldmelt the capabilities into the state table of the "overall goals"("X can be stable / Y can be read / Z can be discovered"); do not open a separate "what capabilities are provided" section.
Starting with "as I understand it" to forcibly fill in missing information——this is the most hidden anti-pattern. When Stage 1 information is insufficient, AI will politely write "as I understand it, you probably want to do X / I assume the current state is Y / your customer volume should be Z"——this is equivalent to filling in from thin air, which will leave all judgments after Stage 2 hanging in the air. The correct response is to output the questions to be filled in according to the "stuck output format" of Stage 1 Step 3,do not force an opening。

In the actual case, the 5 corrections of customer-metrics-service:按数据源切版本 / summary 层塞进底座 / 100 客户过度设计 / 技术细节塞进 plan / 功能清单视角——are concrete manifestations of the first 5 of these 6 anti-patterns.

Abstract case (fictional: customer tag platform v1.0)

Scenario: build a customer tag management platform for internal business teams, with 30 business lines integrated.

The logic of key design decisions(learn the logic, do not copy the wording):

Positioning: "not a BI tool / not a CDP / not a user profiling system, but aunified registration and distribution service for customer tags"——first knock out 3 common misunderstandings
Pain points(fictional example):
- 标签定义散在各业务文档 | 同名标签语义不同,数据对账经常吵架
- 标签发布无审计 | 谁改了什么没记录,出问题查不到
- 下游消费方式单一 | 只能查 Excel,程序化集成难
Overall goals(state description): tags can be registered / definitions can be reused / changes can be traced / data can be read by programs

Version roadmap(one main question per stage):

v0.1 元数据底座 → v0.2 标签登记上线 → v0.3 审计与变更 → v0.4 分发 API → v1.0 正式可用

v0.2 business questions for acceptance:
- "What is the current definition of a certain tag?"
- "Which business lines use this tag?"
- "When was this tag last changed?"
Out-of-scope items with reasons:
- 画像计算 → 属于上层分析服务,不是登记平台职责
- 多租户隔离 → 30 业务线规模下不需要,过度设计
- 标签生效时间窗口管理 → 复杂度高,留到 v2.0

Key pitfalls (same correction experience as customer-metrics-service):

Do not split versions by "data source" (MySQL / Hive / external API); split by capability layer
Do not write fields, table structures, or API paths in the plan
Do not list feature inventories like "provide query capability / provide registration capability / provide audit capability"—melt them into the status table of the "overall goal"

Use cases

Scenario 1: The first "what to do" document after a new project is initiated → There is an architecture baseline / project initiation document above, and "what v1.0 does, in how many steps" needs to be laid out. This is the main battlefield of this skill.

Scenario 2: Major version planning for an existing project → An existing project needs v2.0 / v3.0, and "what the main problem of this version is and how it differs from the previous version" needs to be realigned.

Scenario 3: Multi-stage migration plan → Migrating an old system to a new system requires breaking down "how many stages, what is migrated in each stage, and what counts as success after migration".

Scenario 4: Evolution roadmap for internal tools → An internal script / tool wants to be upgraded to a formal service, and "the steps from tool to service" need to be planned.

Inapplicable scenarios

Document type mismatch

Detailed design document(fields / interfaces / tech stack all complete) → start another detail-design type of document; this skill does not cover it
PRD / requirements document(user stories / acceptance criteria) → use prd-doc-writer
Business description(externally listing feature inventory) → the business description perspective is different; this skill is not applicable
Visit / sharing outline(giving a talk to an external audience) → use share-outline
Weekly report / work summary(organizing things that have already happened) → use weekly-report
Customer consensus meeting preparation(multi-party alignment) → use meeting

Project scale is too small

Script refactoring / bug fixes / small adjustments within 1 week——no framework plan is needed; just write 1 page of "what to do + how to verify"
A "one-time delivery" project that does not need stages——for a project with no distinction between v0.1 / v0.2, this skill will over-structure it
Judgment criteria: If the "stages" you come up with are only 1, or the work in each stage is mutually dependent and cannot be delivered independently—it means this project does not need a framework plan

Notes for multi-person collaboration scenarios

This skill assumes "one owner leads the writing of one plan".In multi-person collaboration scenarios(multiple owners, cross-department, requiring a meeting first for alignment):

For Stage 1-3, it is recommended to first hold 1-2 small meetings to align on "current state / document type / skeleton", then have one person write the main draft
Do not have 3 people arguing for days over the Stage 3 skeleton—the hard gates are meant to stop AI from skipping steps, not to stop team discussion

md → html conversion

Under this skill's tools/ subdirectory, md2html.py scripts and style.cssare provided, used to convert the produced .md into a visualized .html。

.claude/skills/plan-report/
├── SKILL.md          ← skill 本身,给 Claude 读
└── tools/
    ├── md2html.py    ← 转换脚本
    └── style.css     ← 输出 HTML 的样式表

Install dependencies(one-time):

pip3 install markdown

Use:

python3 .claude/skills/plan-report/tools/md2html.py docs/plan/v1.0-框架-{项目名}.md

The output will be generated in the same directory as the md with the same name .html。

The style is controlled by tools/style.css , and can be modified as needed (blue accent / table hover / ASCII blocks, etc.). The script will automatically find the style.cssin the same directory, or you can use the --css parameter to specify another stylesheet.

About this skill

Function Description

Core Principles

1. Gather evidence before designing

2. Document type determines everything

3. State descriptions > action descriptions

4. Split versions, do not pile up features

5. Work backward from acceptance to delivery

6. Non-goals must come with reasons

7. Always serve the reader

Workflow

Stage 1: Grasp reality

Step 0: Quick scale screening (do this before entering Stage 1 to prevent misuse on small projects)

Step 1: Collect the following information (fill in what is known, mark what is unknown as to be supplemented)

Step 2: Hard gate + information depth self-check

Step 3: The "stuck output format" when information is incomplete

Stage 2: Determine the document type

Stage 3: Build the skeleton

Stage 4: Fill in each section (according to the 4 principles)

Principle 1: First define what it is / is not

Principle 2: Find the pain points; do not say "we want to do X"

Principle 3: Split versions, don't pile up features

Principle 4: Use acceptance to reverse-engineer delivery

Stage 5: Use a unified three-part structure for each version

Stage 6: Language refinement

Stage 7: Self-check + save to disk

Templates

Small Project Skeleton (8-9 Sections)

Standard Skeleton (10 Sections)

Example Reference

Actual case (customer-metrics-service v1.0)

Abstract case (fictional: customer tag platform v1.0)

Use cases

Inapplicable scenarios

Document type mismatch

Project scale is too small

Notes for multi-person collaboration scenarios

md → html conversion