用途
/document 是一个文档智能体技能，用于在某个功能通过 /test 测试且用户批准之后，更新项目文档。它的工作目标是在功能实现与验证完成后，把「计划」与「实际」之间的差异完整记录下来，并同步到项目的多个知识文件中。
调用方式为 /document {ID}，其中 {ID} 为任务 ID。
主要能力
1. 完整流水线审计（Step 1）
在写文档前，先做前置检查，确保记录准确：
- 读取主要来源：
docs/task/{ID}-{task-name}.md（计划内容及 /simplify 的实现说明）docs/testing/{ID}-{task-name}.md（测试结果、失败、重试周期）
- 获取实际文件差异：执行
git diff --name-only main...HEAD，并与任务文档中的## File Changes交叉比对。任何出现在 diff 但未出现在任务文档中的文件，说明是 /simplify 或 /test 重试时新增的，即为「流水线缺口」。 - 对流水线缺口分类：资料中提供了一个缺口分类表，类型包括：同文件被大幅重构（/simplify 质量修复）、提取出新 helper/utility（/simplify 单一职责修复）、新增测试夹具或种子文件（/test 设置）、重试时改动的额外文件（/test → /implement 重跑）、周期中途新增迁移文件等，并对应了应更新到 CLAUDE.md 还是 LEARNINGS.md。
- 阅读 /simplify 的实现说明：包括「构建了什么」「与计划的偏离」「标准检查」，中或大的偏离会在文档中体现。
- 检查 /test 重试次数：0 次重试则记录成功经验；1 次及以上则记录失败根因；同一问题多次重试则向 CLAUDE.md 添加「Do Not」条目。
资料明确要求：不要进行大范围代码库探索，只打开缺口清单中的文件或为验证准确性所必需的文件。
2. 识别文档需求（Step 2）
按变更类型决定文档工作：
- 新功能 → 功能文档 + 用户指南
- 增强 → 更新现有文档
- Bug 修复 → 更新故障排查部分
- API 变更 → 更新 API 参考
- 流水线缺口 → CLAUDE.md + LEARNINGS.md
3. 生成文档产出（Step 3）
- 功能文档：
docs/features/{FEATURE}.md，面向开发者的技术实现细节，包含概览、用户旅程、架构（文件结构、schema、API 端点）、关键组件、技术说明。 - 用户指南：
docs/guides/{feature}.md，面向最终用户的使用说明，包含快速开始、分步指引、技巧、FAQ、故障排查。
4. 维护 CLAUDE.md（Step 4）
CLAUDE.md 被定位为「项目大脑」，处理顺序为先读 → 再修剪 → 后更新，绝不只做追加。
- 条目的门槛：如果没有它，未来的智能体会犯错、浪费时间重新发现，或重新讨论已定的决策。
- 更新触发条件表（如新建目录、文件移动/重命名、执行数据库迁移、安装新包、/simplify 抓到重复违规、架构争论有结论、约定被破坏后修复、旧模式被替换）分别对应 Project Structure、Important File Locations、Stack 部分、Do Not、Architecture Decisions、Key Conventions 等位置。
- 可以完全跳过的情况：纯逻辑修复、文案修改，或没有新增文件/目录/迁移/路由/包的样式微调。
- 绝不能跳过的情况：新增迁移、创建新目录、文件移动/重命名、新增 API 路由、需要新环境变量、模式被替换。
5. 复盘与 LEARNINGS.md（Step 5）
- 任务复盘：
docs/learnings/{ID}-{task-name}.md，覆盖整个流水线 —— 计划 vs 现实、质量门发现、测试失败、所做决策。包含：计划 vs 现实（计划了什么、提交了什么、偏离、计划外文件）、/simplify 抓到了什么、/test 揭示了什么、关键经验。 - LEARNINGS.md（项目根目录）：把最有复用价值的洞见追加到相关章节。资料给出「经验来源 → LEARNINGS.md 章节」的映射表，例如 /simplify 抓到编码模式违规 → Common Mistakes to Avoid；/simplify 提取出可复用 helper → Established Coding Patterns；/test 因计划外系统行为失败 → Tech Stack Notes 等。
- LEARNINGS.md 条目规则：一条 = 一条可操作经验；注明是哪个流水线步骤发现的；加粗关键短语并用一句话解释；追加前先检查避免重复。
- 如果 LEARNINGS.md 不存在，则创建并包含章节：Architecture & Decisions、Established Coding Patterns、Common Mistakes to Avoid、Testing Patterns、Tech Stack Notes。
6. 文档检查清单与任务状态
技能内置一份检查清单：是否已运行 git diff 并记录完整文件列表、是否识别并分类流水线缺口、是否阅读 /simplify 实现说明并记录偏离、是否检查 /test 重试次数并找出失败根因、功能文档是否含准确文件路径、用户指南是否创建/更新（若面向用户）、CLAUDE.md 是否读→修剪→更新（或无结构变更时跳过）、复盘文档是否已写、关键经验是否追加且无重复、TASKS.md 中任务是否移入「Approved」。
最后将 TASKS.md 中任务移动到「Approved」状态。
使用方式
- 命令：
/document {ID} - 手动模式：通知用户文档就绪。建议运行
/clear后再运行/ship {ID}。 - 自动模式（任务文档中有
Automation: auto）：输出 SIGNAL 信号后退出，由编排器处理后续路由，不自行启动下一个技能。SIGNAL 格式为：
≡ SIGNAL
STAGE: document
STATUS: DONE
TASK: {ID}
SUMMARY: Feature doc created
REFERENCE: docs/features/{feature}.md
≡ END
适用场景
- 功能已通过测试（/test passes）且用户已批准后，需要沉淀文档时。
- 需要在功能开发完成后同步更新项目知识文件（CLAUDE.md、LEARNINGS.md）时。
- 处于 /implement → /simplify → /test → /document → /ship 这条工作流水线中，作为文档阶段执行。
限制
- 资料明确要求不进行大范围代码库探索，只处理缺口清单或验证准确性必需的文件。
- 该技能在手动模式下不直接执行后续 /ship，需用户另行触发。
- 自动模式下不生成下一个技能，路由由编排器负责。
- 资料未提供除上述内容外的功能、收费、价格、平台或效果信息。