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?

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)

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?"

• 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

• 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}

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?"} ...

• 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

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"

• 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

• "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?"

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

**3 Optional Phrasings for Phase Acceptance**(Choose the most suitable one, do not force-fit the data query type):

| Project Type | Acceptance Phrasing | Example |
|---|---|---|
| **Data / Query Type** | "The system can now answer X / Y / Z" | "How many times did a certain customer call on a certain day / How many Tokens were consumed / What is the main model distribution" |
| **Tool / Process Type**(dashboard, collection, automation) | Status list with "X can be done / Y can be done" | "Newcomers can check the dashboard to judge system status without reading source code / Any of the 6 SREs can run all inspections with one click" |
| **Platform / Service Type** | Three parts: Capability statement + Customer observable signal + Fallback | "API can stably receive alerts / Business parties can confirm whether to send within 30 seconds / Old link is retained without forced switching" |

**Prohibited**: Forcing tool-type acceptance to fit "The system can answer X" — it will result in grammatically awkward sentences like "The system can answer 'Can newcomers get started'" . **Phrasing should adapt to scenarios, not the other way around**.

**Why Unification Is Necessary**:
- 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

**Prohibited**:
- 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

**Follow-up Template**:
- "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?"

---

• "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?"

• 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)

• 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)

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

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

• {...}

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}

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.

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

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.

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

• {Responsibility 1}
• {Responsibility 2}
• {Responsibility 3}

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

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.

• {Deliverable 1}
• {Deliverable 2}
• {Deliverable 3}

• {Business question 1}
• {Business question 2}
• {Business question 3}

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

**Key Constraints**:
- 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

---

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

• 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"

• 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

• 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

• 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