| name | doc-writer |
| description | Guards document creation and modification in the doc/ directory, enforcing 7 standardized type templates (spec, design, plan, rule, guide, report, debt). Validates file naming, header format, and type compliance. Manually triggered via /doc to show the type quick-reference, or auto-triggered when creating/modifying .md files under doc/. Trigger words: "写文档", "新建文档", "文档模板", "/doc". |
文档写作守护
版本：v1.0.0 | 状态：已落地 | 触发：/doc、"写文档"、"新建文档"、"文档模板"
确保 doc/ 下所有文档遵循统一的 7 种类型模板。创建新文档时自动套用模板，修改文档时校验格式。
核心规则
- doc/ 下每个 .md 文件必须属于以下 7 种类型之一，无例外
- 文件名格式：
doc/{type}.{appname}[.{子模块}].md —— appname 优先 + 点分层级（每段 kebab-case，段间用 .，禁止把 appname 和子模块用 - 黏死）。详见 doc/rule.doc.naming.md
- 必须包含标准头部：版本 + 日期 + 状态
- 禁止发明新类型前缀
类型速查表（4W1H + 回顾）
每种类型回答一个不可替代的问题，所以不会再膨胀。
| # | 前缀 | 对应 | 核心问题 | 子类型数 | 包含哪些子类型 |
|---|
| 1 | spec.* | What | 做什么 | 3 | 产品规格、Agent 产品文档、用户故事 |
| 2 | design.* | How | 怎么做 | 2 | 技术设计、技术分析 |
| 3 | plan.* | When | 什么时候做 | 1 | 实施计划 |
| 4 | rule.* | Why not | 为什么不能那样做 | 2 | 规范约定、审计报告 |
| 5 | guide.* | How-to | 怎么操作 | 2 | 操作指南、备忘录 |
| 6 | report.* | What happened | 做了什么 | 1 | 周报 |
| 7 | debt.* | What's owed | 欠了什么 | 1 | 工程债务台账 |
类型选择决策树
要写什么内容？
├── 定义需求/功能/用户故事 → spec.*
├── 描述技术方案/架构/分析 → design.*
├── 规划分步实施/排期 → plan.*
├── 制定规则/记录审计发现 → rule.*
├── 提供操作指南/临时备忘 → guide.*
├── 记录周期性进展 → report.*
└── 记录已知边界/TODO/留尾债务 → debt.*
通用头部格式
所有类型必须包含：
# 标题
> **版本**：v1.0 | **日期**：YYYY-MM-DD | **状态**：草案/规划中/开发中/已落地/已废弃
Agent 规格文档额外要求 appKey 字段。
写作原则与代码使用
写作原则、代码使用规范、合并历史 → 见 reference/writing-principles.md
核心五条：
- 受众分层（前四节非技术读者可读，禁止代码）
- 结论先行
- 代码有节制（技术章节允许代码但需上下文说明，全文 ≤30%）
- 单一职责
- 可扫描（表格 > 列表 > 散文）
模板速查
完整模板详情 → 见 reference/templates.md
spec.* — 产品规格（3 个子类型）
| 子类型 | 适用场景 | 核心章节 |
|---|
| A. 产品规格（默认） | 功能/产品完整需求 | 产品定位 → 核心概念 → 场景流程 → 功能清单 → 数据模型 → 里程碑 |
| B. Agent 产品文档 | Agent "身份证"（含 appKey） | 产品定位 → 角色 → 核心流程 → 功能规格 → 数据架构 → 接口概览 |
| C. 用户故事 | 用户视角需求 + 验收标准 | 角色定义 → US-编号 → 验收标准 → 关联接口 |
design.* — 技术设计（2 个子类型）
| 子类型 | 适用场景 | 核心章节 |
|---|
| A. 技术设计（默认） | 架构方案、技术选型 | 管理摘要 → 问题背景 → 设计目标 → 核心决策 ‖ 整体方案 → 数据设计 → 接口设计 → 影响范围 → 附录 |
| B. 技术分析 | 技术/竞品系统性分析 | 管理摘要 → 现状盘点 → 详细分析 → 建议 → 附录 |
‖ 标记前为非技术读者可读部分（禁止代码），‖ 后为开发者细节（允许精简代码，全文 ≤30%）。
plan.* — 实施计划
| 子类型 | 适用场景 | 核心章节 |
|---|
| 实施计划 | 分步路线图 | 概述 → 前置条件 → 分阶段计划 → 数据变更 → 风险依赖 → 进度追踪 |
rule.* — 规范约定（2 个子类型）
| 子类型 | 适用场景 | 核心章节 |
|---|
| A. 规范约定（默认） | 团队规则、编码规范 | 核心原则 → 为什么 → 规则条目 → 判断标准 → 例外 |
| B. 审计报告 | 系统性检查发现 | 执行摘要 → 发现汇总 → 详细发现 → 后续行动 |
guide.* — 操作指南（2 个子类型）
| 子类型 | 适用场景 | 核心章节 |
|---|
| A. 操作指南（默认） | 教程、操作手册 | 适用场景 → 快速开始 → 详细说明 → 常见问题 |
| B. 备忘录 | 临时调查/调试记录（含有效期） | 背景 → 结论 → 调查过程 → 后续行动 |
report.* — 周报
| 子类型 | 适用场景 | 核心章节 |
|---|
| 周报 | 周期性进展回顾 | 本周概览 → 完成事项 → 关键数据 → 下周方向 |
详细生成流程见 weekly-update-summary 技能。
debt.* — 债务台账
| 子类型 | 适用场景 | 核心章节 |
|---|
| 债务台账 | 模块级未还工程债（已知边界 / TODO / 留尾风险） | 总览（open/paid 计数）→ 债务列表 → 已还归档 |
按模块归档（debt.{module}.md），债务行用 YYYY-MM-DD-{描述} 作 ID，含严重度 / 触发条件 / 状态。详细字段约定见 doc/rule.doc.naming.md §debt.*。
执行流程
当手动触发 /doc 时
展示类型速查表，询问用户要创建哪种类型的文档，然后套用对应模板。
当自动检测到文档操作时
- 创建新文档：检查文件名前缀是否为 7 种之一，套用对应模板
- 修改文档：校验头部格式（版本+日期+状态）是否存在
- 发现旧前缀（story/agent/analysis/audit/memo）：提醒用户该前缀已废弃，建议重命名
