Product Documentation Standard (full-stack-doc v3.0)

Enforces a fixed directory-and-naming convention for product documentation, suitable for general product families. Ready-to-copy Markdown templates live under [templates/](templates/). Detailed file mappings and conventions in [references/structure.md](references/structure.md).

1. When to Use

• Creating or initializing a product documentation repository
• Scaffolding doc trees for product families or standalone products
• Auditing or aligning existing repos against the product doc standard
• Generating / renaming docs to match the naming convention
• Aligning product-docs/ content with the template structure
• Writing or expanding any of the 10 root-level planning documents

2. Start Here

Before copying or editing templates, load only the references needed for the task:

• Placeholder interpretation and secret handling: [references/placeholder-protocol.md](references/placeholder-protocol.md)
• Product/version/module/delivery ownership: [references/document-boundaries.md](references/document-boundaries.md)
• Optional architecture and product patterns: [references/applicability.md](references/applicability.md)
• Reusable example identities and adaptation rules: [references/example-profiles.md](references/example-profiles.md)
• Evidence-oriented completion criteria: [references/quality-rubric.md](references/quality-rubric.md)
• Exact filenames and dependency map: [references/structure.md](references/structure.md)
• Project README selection, evidence, bilingual, and preservation rules: [references/readme-template-guide.md](references/readme-template-guide.md)
• Rust common template and optional domain-profile selector: [templates/readme/rust-profiles/README.md](templates/readme/rust-profiles/README.md)
• Complete architecture template, evidence, and profile selection: [references/architecture-template-guide.md](references/architecture-template-guide.md)

2.1 Placeholder Summary

Replace double-brace placeholders in both filenames and content. Single-brace prompts such as {例如：订单中心} are authoring examples, not global tokens. Root keeps one 6、 file; the former detailed feature list is merged into 10、功能菜单与版本规划.

2.2 Adaptation Contract

1. Inspect the target repository and collect confirmed facts before filling templates.
2. Choose applicable sections; remove non-applicable dual-track, SaaS, DDD/COLA, Agent, CLI/IM, mobile, or enterprise examples.
3. Keep rich examples as labeled examples, but never present them as facts about the target product.
4. Label uncertain content as 推断, 假设, or 待确认 and attach evidence where possible.
5. Preserve source examples when maintaining this skill; improve boundaries and labels instead of deleting depth.
6. Name generated standalone architecture documents -Architecture.md or -Architecture.zh_CN.md; place component/version qualifiers before -Architecture.

3. Document Architecture

3.1 Four-Layer Structure

{{PRODUCT_NAME}}/
├── 1、{{PRODUCT_NAME}}-命名与品牌说明.md          ─┐
├── 2、{{PRODUCT_NAME}}-术语表与词汇表.md          │
├── 3、{{PRODUCT_NAME}}-市场与商业分析.md          │
├── 4、{{PRODUCT_NAME}}-技术与可行性分析.md        │ Root (10) — 产品级，与版本无关
├── 5、{{PRODUCT_NAME}}-技术方案与路线.md          │
├── 6、{{PRODUCT_NAME}}-产品与版本规划.md          │
├── 7、{{PRODUCT_NAME}}-领域模型设计.md            │
├── 8、{{PRODUCT_NAME}}-Architecture.zh_CN.md      │
├── 9、{{PRODUCT_NAME}}-视觉与交互DNA规范.md       │
├── 10、{{PRODUCT_NAME}}-功能菜单与版本规划.md      ─┘
│
├── V1/                                   ─┐
│   ├── 1、{{PRODUCT_NAME}}-需求调研文档-V1.md      │
│   ├── 2、{{PRODUCT_NAME}}-需求分析文档-V1.md      │
│   ├── 3、{{PRODUCT_NAME}}-V1-Architecture.zh_CN.md│ Version (7) — 版本级实施文档
│   ├── 4、{{PRODUCT_NAME}}-功能与界面规划-V1.md    │
│   ├── 5、{{PRODUCT_NAME}}-PRD文档-V1.md           │
│   ├── 6、{{PRODUCT_NAME}}-功能菜单与版本规划-V1.md│
│   ├── 7、{{PRODUCT_NAME}}-UI设计说明-V1.md        │
│   │                                     ─┘
│   ├── 1、{模块A}/                       ─┐
│   │   ├── {{PRODUCT_NAME}}-{模块A}-PRD-V1.md      │ Module (3) — 可选，按模块
│   │   ├── {{PRODUCT_NAME}}-{模块A}-Stitch设计提示词.md │
│   │   └── {{PRODUCT_NAME}}-{模块A}-UI设计说明-V1.md    ─┘
│   └── ...
│
├── 其他/                                 ─┐
│   ├── 1、技术细分模板.md                │
│   ├── 2、功能提测模板.md                │ Delivery (5) — 可选，研发交付
│   ├── 3、测试结果模板.md                │
│   ├── 4、上线通知模板.md                │
│   └── 5、项目运维模板.md                ─┘
│
├── 技术调研/                             ── 技术调研、协议分析（版本无关）
└── assets/                               ── 图片、附件等

3.2 Scope Summary

3.3 Root 10 Documents — Authoring Chain

文档间存在严格的上下游依赖关系，编写时应按顺序递进：

flowchart LR
    D1["1、命名与品牌"] --> D2["2、术语表"]
    D2 --> D3["3、市场分析"]
    D3 --> D4["4、可行性分析"]
    D4 --> D5["5、技术方案"]
    D5 --> D6["6、版本规划"]
    D6 --> D7["7、领域模型"]
    D7 --> D8["8、系统架构"]
    D8 --> D9["9、视觉DNA"]
    D6 --> D10["10、功能菜单"]
    D9 --> D10

4. Scaffolding Workflow

Step 1 — Root Docs

Copy all 10 files from templates/root/ into the project root. Rename each replacing {{PRODUCT_NAME}}:

# Example: ExampleCommerce
for f in templates/root/*.md; do
  name=$(basename "$f" | sed 's/{{PRODUCT_NAME}}/ExampleCommerce/g')
  cp "$f" "product-docs/ExampleCommerce/$name"
done

Step 2 — Version Docs

Create {{VERSION}}/ (e.g., V1/). Copy 7 files from templates/version/. Replace both {{PRODUCT_NAME}} and {{VERSION}} in filenames and content.

Step 3 — Module Docs (optional)

For each functional module, create {{VERSION}}/{{MODULEINDEX}}、{{MODULENAME}}/. Copy 3 files from templates/module/. Replace {{PRODUCTNAME}}, {{MODULENAME}}, and {{VERSION}}.

Example (ExampleCommerce V1 商品采集):

V1/1、商品采集/
├── ExampleCommerce-商品采集-PRD-V1.md
├── ExampleCommerce-商品采集-Stitch设计提示词.md
└── ExampleCommerce-商品采集-UI设计说明-V1.md

Step 4 — Delivery Docs (optional)

Copy templates/delivery/ into 其他/ or a dedicated delivery folder. Replace {{PRODUCT_NAME}} and dates.

Step 5 — Special Directories

Create 技术调研/ for tech research and 其他/ for non-standard docs. Directories like demo/, assets/, .stitch/ stay untouched.

Step 6 — Validate

Run the validation checklist (Section 7).

5. Quality Standards

5.1 Evidence-Oriented Quality Gates

Line counts, table counts, and diagram counts are diagnostics, not acceptance gates. A document is complete when it enables the next decision or delivery step with traceable evidence.

Use [references/quality-rubric.md](references/quality-rubric.md) for scoring. Add diagrams and tables only when they make a relationship or comparison materially clearer.

5.2 Universal Document Structure

每份 root 文档 必须 包含以下标准结构：

文档头部:

# {{PRODUCT_NAME}} 文档标题

> **文档说明**：一句话说明文档用途与范围。
>
> **版本**：V1.0.0
> **最后更新**：{{DATE}}

文档尾部:

---

**文档版本**：V1.0.0
**创建日期**：{{DATE}}
**最后更新**：{{DATE}}
**文档状态**：✅ 待评审

5.3 Formatting Conventions

5.4 Cross-Reference Rules

• Doc 3 关联文档必须链接 Doc 1（品牌边界）和 Doc 5（技术可行性）
• Doc 5 Gantt 日期必须与 Doc 6 版本里程碑、Doc 10 发布节奏一致
• Doc 7 聚合名称必须在 Doc 2 术语表中有定义
• Doc 8 分层名称必须与 Doc 5 技术选型对应
• Doc 10 功能列表的版本标注必须与 Doc 6 版本矩阵一致

6. Gotchas

• Sequence numbers 1–7 in version folders are reserved for the 7 standard docs. Non-standard docs must use 8+ or go into 其他/.
• Root has one file numbered 6、 (产品与版本规划). Detailed feature lists are embedded in 10、功能菜单与版本规划.
• Don't reorganize special directories (demo/, assets/, .stitch/, stitch_*, 实施指南/) unless the user explicitly requests it.
• Delivery templates are optional and do not occupy root-level standard sequence numbers.
• When a product has open-source + commercial dual-track (e.g., ExampleCommerce-Open/ExampleCommerce), each track gets its own full 10-doc set with cross-references.

7. Validation Checklist

Run the bundled structural validator from the skill directory:

python3 scripts/validate_templates.py

For generated standalone architecture documents, validate filenames before delivery:

python3 scripts/validate_architecture_filenames.py \
  docs/ExamplePlatform-Architecture.md \
  docs/ExamplePlatform-Architecture.zh_CN.md

Then review semantic consistency that cannot be reduced to file counts:

• Target facts are evidence-backed; examples remain labeled examples
• Root/version/module/delivery responsibilities do not duplicate ownership
• Non-applicable dual-track, DDD/COLA, Agent, SaaS, CLI/IM, mobile, or enterprise sections were removed or adapted
• Timeline dates agree across market, technology, version, and menu documents
• Terminology agrees with the glossary; menu, route, API, and state names agree across PRD/UI/architecture
• Requirements have observable acceptance criteria and failure/permission/empty/loading states where relevant
• No resolved passwords, tokens, private paths, or private product/repository names were introduced
• Standalone architecture filenames match -Architecture.md or -Architecture.zh_CN.md

8. Template Inventory

The original 25 lifecycle templates intentionally retain detailed reusable content and labeled full examples. The README family adds four type-specific templates plus one complete reference; the Rust template adds seven composable profile documents. The architecture family adds one complete master template and seven profile documents. Do not replace any of them with short empty shells.

9. Related Skills

• doc-coauthoring: Interview-driven collaborative document drafting. Install with: npx skills add full-stack-skills/document-skills --skill doc-coauthoring.
• api-doc-generator: Source/OpenAPI-driven API documentation. Install with: npx skills add full-stack-skills/document-skills --skill api-doc-generator.

10. Completion Contract

Before reporting completion, state which template groups were used, which optional patterns were removed, which claims remain assumptions/TBD, and which validation commands passed. For standalone architecture outputs, report the filename validation result. If the target repository could not be inspected, say so explicitly rather than presenting example content as confirmed facts.