documentation-specialist

name	documentation-specialist
description	查阅、生成、更新、对齐和审校项目文档时使用。适用于 README、设计说明、变更说明、技能文档、计划文档与规范文档，不假设文档一定在 docs/ 目录下。用户提到 docs、documentation、README、设计文档、同步文档、更新说明时都应触发。
metadata	{"internal":true}

Documentation Specialist

铁律：不要把文档写成愿景或猜测。文档必须反映代码、配置和决策的当前事实。

工作流

• Step 1: 确认文档类型 ⚠️ REQUIRED
  • 1.1 判断这是规范文档、设计说明、使用说明、变更记录还是技能文档。
  • 1.2 明确读者是谁，以及文档需要回答什么问题。
• Step 2: 收集权威来源 ⚠️ REQUIRED
  • 2.1 从代码、配置、现有文档和提交意图中提取事实。
  • 2.2 当事实不充分时，先标记未知点，不要自行脑补。
• Step 3: 组织内容
  • 3.1 先写结构，再补细节、命令、示例和链接。
  • 3.2 需要交叉引用时，保证路径和标题真实可用。
• Step 4: 做同步检查
  • 4.1 核对文档是否与当前代码和工作流一致。
  • 4.2 如果代码已变更但文档无法完整更新，明确写出缺口。

关注点

• 标题是否准确反映读者任务。
• 示例命令是否真实可执行。
• 链接、路径、技能名和脚本名是否存在。
• 文档是否说明限制、前提和后续动作。

项目特化提示

• 如果仓库中存在 docs/，优先检查 standards/、design/、plan/ 等子目录，而不是假设所有文档都在根目录。
• 需要图表时优先使用 Mermaid，而不是嵌入难维护的图片描述。
• 当代码或技能流程发生重大变化时，优先更新 README、设计文档和技能文档中的命令与路径。

反模式

• 假设 docs/ 一定存在，并围绕不存在的目录写文档。
• 复制代码结构却不解释为什么这样设计。
• 用口号替代操作步骤和限制条件。

交付前检查

• 文档结论都有代码、配置或既有文档作为依据。
• 路径、链接、技能名和命令都已核对。
• 已明确文档面向的读者和使用场景。
• 未把未知信息伪装成既定事实。