Framework Plan Report Assistant

Function Description

Core Principles

1. Validate Before Designing

2. Document Type Determines Everything

3. State Description > Action Description

4. Split Versions, Don't Stack Features

5. Derive Deliverables from Acceptance Criteria

6. Non-Implementation Items Must Include Reasons

7. Always Serve the Reader

Can a person who has never been exposed to this project understand why the project was initiated, what counts as completion, and whether it is useful to them after reading it?

Workflow

Stage 1: Understand Reality

Step 0: Scale Quick Screening(Do before entering Stage 1 to avoid misusing for small projects)

1. Estimated time: < 1 week / 1 week - 6 weeks / > 6 weeks?
2. Number of independently deliverable phases: 1 / 2-3 / 4+?

• Estimated < 1 week and only 1 phase can be split → Explicit exit: "This scenario does not require a framework plan, it is recommended to use a 1-page document of 'What to do + How to verify'"
• Estimated 1-6 weeks + 2-3 phases → Use small project skeleton(8-9 sections, see "Templates" section)
• Estimated > 6 weeks / 4+ phases → Use standard skeleton(10 sections)

Step 1: Collect the following information(Fill in known items, mark unknown as to be supplemented)

1. Project Background: Project name, current phase(initiated / in progress / transformation) / Whether there is an upper-layer architecture baseline
2. Current Status: Existing code / What existing systems can do / What data can be obtained / What the output format is
3. Target Consumers: Who this plan is for / Who will act based on it
4. Hard Constraints: Technical constraints(API rate limits, data windows, storage limits), business constraints(scale, rhythm, budget), organizational constraints(who is responsible, launch time)

• "What parts can be run now? Can you run it to show me the actual output?"
• "Are there upper-layer documents(architecture baseline, project initiation document, research report) I should read first?"
• "Who is this plan for — internal R&D / cross-team / customers?"
• "Are there any known hard constraints? Such as API rate limits, launch deadlines, customer volume limits?"

Step 2: Hard Gate + Information Depth Self-Check

• Do not proceed to Stage 2 unless you can answer "What is the current status / What can be obtained / What are the hard constraints / Who will consume" in 3 lines
• Designing out of thin air is the easiest pitfall for this skill — Writing without understanding reality = all subsequent decisions are unfounded

• Current status answers must include specific numbers / system names / data scales(e.g., "50+ business lines", "12 bash scripts", "20 million customers"), only adjectives("quite a lot", "many") do not pass the gate
• Hard constraint answers must include specific values / time limits / interface restrictions(e.g., "Feishu API 100 QPS", "Hive query 10-30 seconds"), "Heard there are limits" does not pass the gate
• If all answers are vague adjectives, return to the follow-up template to ask each question thoroughly, do not force pass the gate

Step 3: "Stuck Output Format" When Information Is Incomplete

# {Project Name} v1.0 Plan — Stage 1 Stuck, Information to Be Supplemented

## Collected Information

- Project Background: {Known part / To be supplemented}
- Current Status: {Known part / To be supplemented}
- Target Consumers: {Known part / To be supplemented}
- Hard Constraints: {Known part / To be supplemented}

## Specific Questions to Follow Up with Users

1. {Specific question 1, e.g., "Which systems are the documents scattered in? How many?"}
2. {Specific question 2, e.g., "Number of users: 30 / 300 / 3000?"}
3. {Specific question 3, e.g., "What was the specific scenario of the last 'unpleasant to use' experience?"}
...

## Minimum Standard to Enter Stage 2

After receiving answers to the above questions, ensure you can answer "What is the current status / What can be obtained / What are the hard constraints / Who will consume" in 3 lines.

Stage 2: Confirm Document Type

• It answers: Why do it / What counts as completion / Who uses it / What not to do / What steps to take / Phase acceptance criteria
• It does NOT answer: fields, interfaces, tech stacks, directories, cron expressions, concurrency models

• "Who is this document mainly for? For people doing the work → leans towards detailed design; for people understanding the work → framework plan"
• "What problem do you expect it to solve? — 'Align the team on what to do / what counts as completion' is framework plan; 'Let business parties know what they can use' is business specification"

• Do not build the skeleton until the document type is confirmed
• Misaligned type = the entire document is invalid, this step must be stuck

Stage 3: Build the Skeleton

Positioning → Pain Points → Boundaries → Phases → Acceptance

1. Project Positioning          (What it is / What it is not)
2. Why Do It                   (Core pain points)
3. Service/System Boundaries   (Responsibilities / Non-responsibilities)
4. v1.0 Overall Goal          (What counts as completion)
5. Version Roadmap            (Steps, only one-line flowchart)
6. v0.1 Phase                 (Problem to solve / Key deliverables / Phase acceptance)
7. v0.2 Phase                 (Same three-part structure as above)
8. v0.3 Phase                 (Same three-part structure as above)
9. v0.4 Phase                 (Same three-part structure as above)
10. Considerations After v1.0  (Not done in this version, each with reason)
11. (Optional) Related Documents — If all upper-layer documents are empty, **delete the entire section**, do not leave a "To be supplemented" placeholder

• First present the skeleton as a whole to the user, allowing them to add/delete chapters or adjust the order
• Prohibited: Modify the skeleton while writing
• Prohibited: Start filling content without user confirmation

• "Is this skeleton correct? Are there any chapters to add / remove / reorder?"
• "How many phases to set? — Derive from 'Each phase solves one core problem', usually 3-5 is appropriate"

Stage 4: Fill in Content Section by Section(Follow 4 Principles)

Principle 1: First Define What It Is / What It Is Not

Principle 2: Find Pain Points, Don't Say "Need to Do X"

• Small projects(<6 weeks / <2 person-months): 3-4 lines are 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 mentioned in production accident reviews / business party complaints? Yes → keep; No → delete.

P1. Multiple businesses repeatedly collect data

Duplicate collection | Daily reports, customer analysis, and value assessment each pull data separately, wasting maintenance costs

Principle 3: Split Versions, Don't Stack Features

v0.1 Base can run → v0.2 Core business caliber imported → v0.3 Monitoring perspective completed → v0.4 Usable by upper-layer business → v1.0 Officially available

Principle 4: Derive Deliverables from Acceptance Criteria

• "If this section is applied to another project, does it still hold? If yes, it means you are writing empty words, rewrite it to be more specific"
• "Is this pain point real, or just our imagination? Can business parties perceive it?"
• "Can this version be split further? If a version needs to do three different things A B C at the same time, it may not be split enough"
• "Is this acceptance a technical indicator or a business question that can be answered?"

Stage 5: Use Unified Three-part Structure for Each Version

### v0.X {Phase Title}:{One-sentence Main Line}

**Problem to Solve**

{2-3 sentences explaining why this phase exists / what happens if not done}

**Key Deliverables**

- {Deliverable 1}
- {Deliverable 2}
- {Deliverable 3, no more than 5-6 items}

**Phase Acceptance**

{Choose one phrasing based on project type}

• Readers can easily compare phases horizontally(v0.1 vs v0.2's problems, deliverables, acceptance criteria)
• Less likely to become a running account
• Will not prematurely dive into technical implementation
• Each phase appears "equally weighted", avoiding some phases being overly detailed while others are perfunctory

• v0.1 uses "What to do / Value", v0.2 uses "Goal / Deliverables", v0.3 creates its own format
• Add extra subsections in a phase(e.g., "Risks", "Dependencies") unless added to every phase

• "Try using the 'The system can answer X' phrasing for each phase's acceptance criteria, see if it flows smoothly"
• "This deliverable list has more than 6 items, should we cut it? Or does it mean this phase is not split enough?"

Stage 6: Language Polishing

• "Does this paragraph read like 'I'm explaining something to you' or 'I'm listing what we need to do'? The latter needs to be revised"
• "Can this bullet point be clearly stated using the 'X can Y' state description?"

Stage 7: Self-Check + Finalize

• Core Question: Can a陌生 reader understand "Why the project was initiated / What counts as completion / Whether it is useful to them" after reading?
• Type Purity: Does the document include fields, interfaces, tech stacks, directory naming, cron expressions? If yes → delete
• Pain Point Authenticity: Is each pain point perceivable by business parties, or just something the author thinks "should be mentioned"? Use the 3-second judgment method: Can it be mentioned in accident reviews / business party complaints
• Version Splitability: Does each version only solve one core problem? If a version does A B C at the same time, either split it or merge it into the next version
• Three-part Structure Discipline: Do all phases strictly use the "Problem to solve / Key deliverables / Phase acceptance" three-part structure? Does any phase create its own format?
• State Description: Are overall goals and acceptance criteria all in "can X" phrasing, or mixed with action descriptions?
• Non-Implementation Items with Reasons: Does each "Not doing" item in Section 10 have a "Why not include in current version" explanation?
• Business Questions: Does the acceptance criteria include the "The system can now answer X / Y / Z" phrasing?
• Unified Naming: Does the entire document use "v1.0", "First phase", "Initial version" — use one, do not mix
• Boundary vs Non-Implementation Deduplication(New): Is there semantic confusion between Section 3 "Non-responsibilities" and Section 10 "Considerations after v1.0"? — The former is "Never do"(responsibility boundary), the latter is "Not done in this version but may be done later"(scope boundary)
• Technical Constraints Translated to Business Language(New): Are the project's hard constraints(API rate limits, data windows, compliance, etc.) written in business language in the "Problem to solve" section, instead of being thrown out as technical details?
• Over-structuring Reverse Check(New): For each table / each phase, ask "If this row / this phase is removed, does the document still hold? If yes, delete it."
• No Forced Line Count(New): Are the number of lines for overall goals / pain point tables / non-implementation items "forced to fill"? — If there is a line that is particularly vague and looks like "perfunctory task", delete it

• Default path:

  docs/plan/{version}-{topic}-{project-name}.md

  , e.g.,

  docs/plan/v1.0-framework-customer-metrics-service.md

• Synchronously generate HTML(use this skill's md → html tool, see end)

Templates

• Small projects(1-6 weeks / 2-3 phases)→ Use small project skeleton(8-9 sections)
• Medium and large projects(>6 weeks / 4+ phases)→ Use standard skeleton(10 sections)

Small Project Skeleton(8-9 Sections)

# {Project Name} {Version} Framework Plan

> Status: Framework Plan Version
> Date:{YYYY-MM-DD}
> Project Scale: Small(1 person X weeks / Y phases)

---

## 1. Project Positioning

{Project Name} is a **{1-sentence core positioning}**.

**It does**:{X specific things it can do, within 3 lines}
**It does not do**:{Y specific things it clearly does not do, within 2 lines, distinguish from "After v1.0"}

> Internal tool-type projects: Use "It does / It does not do" comparison format, do not force "Not A / B / C" misunderstandings

---

## 2. Why Do It

| Problem | Impact |
|---|---|
| {Real pain point 1} | {Specific consequence} |
| {Real pain point 2} | {Specific consequence} |
| {Real pain point 3} | {Specific consequence, 3-4 lines are enough, do not fill in} |

---

## 3. {Version} Overall Goal

| Goal | Description |
|---|---|
| {State 1, "can X" phrasing} | {Description} |
| {State 2} | {Description} |
| {State 3, 3-4 lines are enough} | {Description} |

---

## 4. Version Roadmap

```text
v0.1 {Phase Slogan} → v0.2 {Phase Slogan} → v0.3 {Phase Slogan} → {Version} Available
```

---

## 5. v0.1 {Title}

### Problem to Solve
{...}

### Key Deliverables
- {...}

### Phase Acceptance
{Use tool-type / platform-type phrasing, see Stage 5 three-part alternatives}

---

## 6. v0.2 {Title}
(Same three-part structure as above)

## 7. v0.3 {Title}
(Same three-part structure as above)

---

## 8. What to Consider After {Version}

| Future Direction | Why Not Include in {Version} |
|---|---|
| {Non-implementation item 1} | {Reason} |
| {Non-implementation item 2} | {Reason, 2-3 lines are enough} |

• No Section 3 "Service Boundaries" — merged into Section 1 "It does / It does not do"
• No "Related Documents" section — small projects usually have no upper-layer documents
• Overall Goal 3-4 lines(not 6 lines)
• Pain Points 3-4 lines(not 5 lines)
• 2-3 phases(not 4)

Standard Skeleton(10 Sections)

# {Project Name} {Version} Framework Plan

> Status: Framework Plan Version, technical details to be addressed in detailed design phase
> Date:{YYYY-MM-DD}
> Upper-layer Documents:{Path to architecture baseline / project initiation document, if any}

---

## 1. Project Positioning

{Project Name} is a **{1-sentence core positioning}**.

Its goal is **not** {Common misunderstanding 1} {/ misunderstanding 2 / misunderstanding 3 — based on actual situation, 1-3, better to lack than force}, **but** {Correct positioning}.

> **If it is an internal tool-type project** and no real misunderstandings can be thought of, use comparison format:"It does X / does not do Y", do not force misunderstandings.

One-sentence summary:

```text
{Core action chain, e.g.: Unified collection → Unified沉淀 → Unified caliber → Unified interface → Used by upper-layer business}
```

---

## 2. Why Do It

Currently {1-sentence current status}. This brings several long-term problems:

| Problem | Impact |
|---|---|
| {Pain point 1} | {Specific consequence 1} |
| {Pain point 2} | {Specific consequence 2} |
| {Pain point 3} | {Specific consequence 3} |
| ... | ... |

> **Number of lines based on actual pain points, do not fill in**: Small projects 3-4 lines / medium projects 4-5 lines / large projects 5-7 lines. **3-second Judgment Method**: Can this pain point be mentioned in production accident reviews / business party complaints? Yes → keep; No → delete.

{Version} aims to solve these basic problems, not to complete all {business/capabilities} at once.

---

## 3. Service Boundaries

{Project Name} is only responsible for **{Core responsibilities}**.

```text
{Upstream / Input}
   ↓
{This Project}   ← Current document
   ↓
{Downstream / Consumers}
```

This project is responsible for:

- {Responsibility 1}
- {Responsibility 2}
- {Responsibility 3}

This project is not responsible for:

- {Non-responsibility 1}
- {Non-responsibility 2}
- {Non-responsibility 3}

These capabilities belong to {Owner}.

---

## 4. {Version} Overall Goal

The goal of {Version} is to achieve {state description}, not {easily misunderstood larger goal}.

| Goal | Description |
|---|---|
| {State 1, "can X" phrasing, e.g., "Data can be stably imported"} | {1-sentence description} |
| {State 2} | {1-sentence description} |
| {State 3} | {1-sentence description} |
| ... | ... |

> **Number of lines based on actual states, do not fill in**: Small projects 3-4 lines / medium projects 4-5 lines / large projects 5-6 lines.
> **"Old link can fallback" is a specific line for the example project customer-metrics-service(because there is the maas_bot old link) — do not treat it as a mandatory template item. If a new project has no "old link", do not include this line.**

{Version} does not pursue {explicitly excluded excessive goals}, only needs to achieve {core goal}.

---

## 5. Version Roadmap

{Version} is split into N internal phases for advancement. Each phase only solves one core problem.

```text
v0.1 {Phase Slogan}
  ↓
v0.2 {Phase Slogan}
  ↓
v0.3 {Phase Slogan}
  ↓
v0.4 {Phase Slogan}
  ↓
{Version} Officially Available
```

---

## 6. v0.1 {Phase Title}:{One-sentence Main Line}

### Problem to Solve

{Why this phase is needed / what happens if not done}

### Key Deliverables

- {Deliverable 1}
- {Deliverable 2}
- {Deliverable 3}

### Phase Acceptance

{1-2 sentences of state description + "The system can now answer X" phrasing}

---

## 7. v0.2 {Phase Title}:{One-sentence Main Line}

### Problem to Solve

...

### Key Deliverables

...

### Phase Acceptance

After this phase, the system can answer:

- {Business question 1}
- {Business question 2}
- {Business question 3}

---

## 8. v0.3 ...

...

---

## 9. v0.4 ...

...

---

## 10. What to Consider After {Version}

{Version} only solves "{core goal}". The following items are not included in the main goal of {Version}:

| Future Direction | Why Not Include in {Version} |
|---|---|
| {Non-implementation item 1} | {Reason 1} |
| {Non-implementation item 2} | {Reason 2} |
| {Non-implementation item 3} | {Reason 3} |

The core principle of {Version} is:

```text
{One-sentence principle, e.g., "Stabilize the data base first, then expand computing and product capabilities"}
```

---

## Related Documents

- Upper-layer Documents:{Path}
- Project Memory:{Path}
- Old Code Reference:{Path}

• All phases(v0.1-v0.4) must use the unified three-part structure, do not add extra subsections to any phase
• No field names, table names, interface paths, tech stacks, directory paths, cron expressions
• Non-implementation items must have a "Why not include in current version" column
• Plain titles, no excessive modifiers

Reference Examples

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

docs/plan/v1.0-framework-customer-metrics-service.md

• Project positioning first uses "Not X / Y / Z, but Z" to eliminate misunderstandings — "Not for customer value scoring, ROI analysis or daily report pages, but to unify scattered data"
• Section 4 overall goal uses 6 lines of "can X" phrasing — Data can be stably imported / Can be stably沉淀 / Caliber can be unified / Can be read by programs / Failures can be detected / Old link can fallback
• All 4 phases use the unified three-part structure, acceptance criteria all use "The system can now answer X / Y / Z" phrasing
• Section 10 non-implementation items use "Future Direction | Why Not Include in v1.0" table, each with reason
• Conclude with a slogan:"Stabilize the data base first, then expand computing and product capabilities"

1. Split versions by "input resources"(data sources / customer types / third-party dependencies)→ Should split by capability layers(foundation → business access → external service). Ask yourself: Can each version independently deliver a "user-perceivable capability"? No → split incorrectly.
2. Include "business computing / upper-layer processing" in your service boundary → Should clearly define "I only reach the factual data layer, business computing belongs to independent modules". Ask yourself: If this responsibility is removed, does my service still exist? Yes → should remove it.
3. Over-design for future maximum scale(concurrency pools / queues / aggregated alerts / multi-tenancy)→ Should design for current v1.0 actual scale, leave interfaces unimplemented. Ask yourself: Is this complexity really needed for v1.0, or "if there are 100x users"?
4. Write technical details(directory structure / Docker / tech stack / cron expressions / fields) into the framework plan → Should extract all of them to the "Detailed Design Document". Ask yourself: If this paragraph is implemented with a different tech stack, does it still hold? Yes → it is business-related, keep it; No → delete.
5. Write "framework plan" as "business capability list"(list "Provide X / Y / Z functions")→ Should integrate capabilities into the state table of "Overall Goal"("X can be stable / Y can be read / Z can be detected"), do not open a separate "What capabilities are provided" chapter.
6. Start with "From my understanding" to force supplement missing information — This is the most hidden anti-pattern. When information is insufficient in Stage 1, AI will politely write "From my understanding you probably want to do X / I assume your current status is Y / Your customer scale should be Z" — This is equivalent to unfounded completion, making all subsequent judgments after Stage 2 unfounded. The correct response is to output the to-be-supplemented questions according to the "Stuck Output Format" in Stage 1 Step 3, do not force start writing.

Split versions by data source / Include summary layer in base / Over-design for 100 customers / Include technical details in plan / Feature list perspective

Abstract Case(Fictional: Customer Tag Platform v1.0)

• Positioning: "Not a BI tool / Not a CDP / Not a user portrait system, but a unified registration and distribution service for customer tags" — first eliminate 3 common misunderstandings
• Pain Points(Fictional example):

  • Tag definitions scattered in various business documents

    |

    Same-named tags have different semantics, data reconciliation often causes conflicts

  • No audit for tag release

    |

    No record of who changed what, hard to investigate when problems occur

  • Single downstream consumption method

    |

    Only can check Excel, difficult to integrate programmatically

• Overall Goal(State description): Tags can be registered / Definitions can be reused / Changes can be traced / Data can be read by programs
• Version Roadmap(One core problem per phase):

  v0.1 Metadata base → v0.2 Tag registration launched → v0.3 Audit and changes → v0.4 Distribution API → v1.0 Officially available

• v0.2 Acceptance using business questions:
  • "What is the current definition of a certain tag?"
  • "Which business lines are using this tag?"
  • "When was this tag last changed?"
• Non-implementation items with reasons:

  • Portrait calculation → Belongs to upper-layer analysis service, not the responsibility of the registration platform

  • Multi-tenant isolation → Not needed for 30 business lines, over-design

  • Tag effective time window management → High complexity, leave to v2.0

• Do not split versions by "data source"(MySQL / Hive / external API), split by capability layers
• Do not write fields, table structures, API paths in the plan
• Do not list feature lists like "Provide query capabilities / Provide registration capabilities / Provide audit capabilities" — integrate into the state table of "Overall Goal"

Application Scenarios

Inapplicable Scenarios

Document Type Mismatch

• Detailed Design Document(complete with fields / interfaces / tech stacks)→ Start another

  detail-design

  type document, this skill does not involve
• PRD / Requirements Document(user stories / acceptance criteria)→ Use

  prd-doc-writer

• Business Specification(list feature lists externally)→ Different perspective from business specification, this skill is not applicable
• Visit / Sharing Outline(Give a talk to external audience)→ Use

  share-outline

• Weekly Report / Work Summary(Organize completed items)→ Use

  weekly-report

• Customer Consensus Meeting Preparation(Multi-party alignment)→ Use

  meeting

Project Scale Too Small

• Script modification / bug fix / small adjustment within 1 week — No need for framework plan, directly write a 1-page "What to do + How to verify" document
• One-time delivery projects that do not need phase splitting — Projects without v0.1 / v0.2 phases, this skill will over-structure them
• Judgment Standard: If you can only think of 1 "phase", or the tasks in each phase are interdependent and cannot be delivered independently — it means this project does not need a framework plan

Notes for Multi-person Collaboration Scenarios

• It is recommended to hold 1-2 small meetings in Stage 1-3 to align "Current status / Document type / Skeleton", then let one person take the lead in writing
• Do not let 3 people argue over the Stage 3 skeleton for days — hard gates are used to prevent AI from skipping steps, not to block team discussions

md → html Conversion

tools/

md2html.py

style.css

.md

.html

.claude/skills/plan-report/
├── SKILL.md          ← Skill itself, for Claude to read
└── tools/
    ├── md2html.py    ← Conversion script
    └── style.css     ← Style sheet for output HTML

pip3 install markdown

python3 .claude/skills/plan-report/tools/md2html.py docs/plan/v1.0-framework-{project-name}.md

.html

tools/style.css

style.css

--css