通用写作（Writing）

知道了什么，和让别人也知道，是两种完全不同的能力。 本 skill 是后者——把已有的知识、决策、进展，变成不同读者能看懂、愿意看的文档。

核心理念：组件驱动，不预设模板

写作不是"按模板填空"，而是"把内容装进合适的组件、组合成文档"。

传统模板派：先选模板（spec / PRD / 汇报）→ 模板说必备 X 章节 → 内容硬塞进去
本 skill：先看内容形态 → 挑能装这种形态的组件 → 自然组合

为什么不再用"模式 → 模板"？

• 真实内容很少正好匹配某个模板（比如同一份汇报里既有数据又有架构方案）
• 模板的"必备章节"会让简单内容膨胀、复杂内容装不下
• 写作的核心判断是"这段内容长什么样、用什么组件能讲清楚"，模板分类只是干扰

核心资源：

• references/components.md — 写作组件库（HTML / Markdown / 图示组件）。这是本 skill 最重要的索引文件
• references/templates/*.md — 常见组合范式（spec / plan / PRD 等）。是参考，不是规定
• references/report-template.html — 浅色阅读型 HTML 报告组件示例集
• references/templates/report-pitch.html — 深色路演型 HTML 报告组件示例集

第一步：理解内容

收到写作请求后，先理解内容长什么样——不是先选"写哪种文档"。

1.1 内容形态分析

问自己以下问题（已知的跳过，模糊的追问用户）：

1.2 输出格式判断

HTML 不再硬分"汇报型 vs 路演型"——同一份 HTML 可以混合 Hero（路演风）+ Metric-Card（数据）+ Figure（架构图）。看内容选组件，不看"汇报子模式"。

1.3 与用户对齐（仅当模糊时）

把你的理解告诉用户，让用户确认或修正：

我的理解：
- 内容核心：xxx
- 读者：xxx
- 形态识别：含决策（3-4 项）/ 架构图（2 张）/ 风险点（5 个）
- 推荐格式：HTML（路演风格 + 数据指标混合）
- 存放：docs/reviews/

确认开始？

简单明确的需求（"帮我写个 spec 改造 session 模块"）跳过对齐，直接进下一步。

第二步：选组件

根据 1.1 识别出的内容形态，到 references/components.md 查找对应组件。

速查表（完整版见 components.md 的"H. 组合速查"）：

组件选择原则：

• 同样的内容能用更轻的组件就用更轻的（能用列表别用 grid，能用 grid 别用 vs-block）
• 组件存在是为了表达内容，不是为了视觉好看——没有对应内容就别用对应组件
• 单一文档内组件不要堆叠超过 8-10 种，会变成"组件展示馆"

第三步：参考组合范式（可选）

references/templates/*.md 下有几份常见组合范式——某些类型的文档历史上常用什么章节顺序。这是参考不是规定：

借鉴方式：

• 内容跟范式贴合 → 借鉴章节顺序
• 内容只覆盖部分 → 删掉用不到的章节，不要硬写
• 内容超出范式 → 自由加章节
• 章节存在的理由必须是"内容需要它"，不是"模板要求它"

不参考也行——内容形态清晰时直接进第四步。

第四步：素材就位

动笔前确认素材是否充足：

素材不足时：主动告知用户缺少什么信息，不要编造。如果需要调研，引导用户使用 deep-research skill。

第五步：撰写

按"组件 + 内容"组合输出。遵循以下通用准则：

5.1 通用写作准则

• 中文为主：正文中文，代码 / 命令 / 专有名词保留英文
• 措辞精确：避免"大概""好像""可能"等模糊用语
• 数据优先：能用数据说明的不用形容词
• 结构服务内容：表格 / 列表 / 卡片是为了表达更清楚，不是为了好看
• 篇幅自适应：根据内容复杂度自然决定篇幅，不人为压缩也不注水
• 图表有效：需要图表调 diagram skill 生成；简单流程用 ```flow 代码块；调用关系超过 5 个节点才考虑流程图

5.2 按读者类型微调

5.3 HTML 报告写作流程

1. 决定基调：浅色阅读型（report-template.html）还是深色路演型（templates/report-pitch.html）——也可以混合
2. Read 对应的组件示例 HTML 文件（看可用类名）
3. 按 components.md 挑组件、按内容组装
4. 调 diagram skill 生成图表（评审场景图带标题，文档配图不带——见 diagram skill）
5. Write 输出
6. open 命令打开供 review

5.4 Markdown 文档写作流程

1. 按 1.1 识别内容形态 → 选组件（多数 MD 组件 = 表格 / 列表 / 标题 / 代码块）
2. （可选）参考 references/templates/*.md 找组合范式
3. 直接写
4. 调 preview-md skill 在浏览器预览

第六步：质量自检

写完后自动执行以下检查：

自检发现问题直接修复，不需要告知用户。

第七步：交付

与其他 skill 的关系

deep-research → 调研结论 → writing（把调研写成文档）
tech-evaluation → 选型结论 → writing（把选型写成方案）
task-start → 对焦结论 → writing（写 spec / plan）
task-finish → 复盘结论 → writing（写 decisions / 汇报）

writing 调用：
  ← diagram skill（生成图表嵌入文档）
  ← preview-md skill（Markdown 文档预览）

边界划分：

• writing vs deep-research：deep-research 负责"搞清楚"（调研过程），writing 负责"写清楚"（文档产出）。deep-research 内部的报告撰写是调研流程的一部分，writing 不接管
• writing vs task-start：task-start 负责"什么时候需要写 spec/plan"（流程调度），writing 负责"怎么写好"（写作质量）

反模式

• ❌ 先选"写哪种文档"再填模板——应该先看内容形态再选组件
• ❌ 因为模板说"必备章节"就硬写——章节存在的理由是内容需要它
• ❌ 因为有 hero 组件就给所有 HTML 加 hero——内部 spec 不需要 hero
• ❌ 因为有 decision-card 三色就把普通结论包成 decision——decision 是为"已决/未决/风险"三态信号化设计的
• ❌ 因为有 metric-card 就编数字凑指标——没数字就别用
• ❌ 单一文档堆叠 ≥ 10 种组件——变成"组件展示馆"
• ❌ 把"组合范式"误读为"必备模板"——templates/*.md 是参考不是规定