当团队已做出决策、需要把研究固化为权威文章时…

把已有的研究笔记提升为知识库中 status: stable 的权威文章，并保留可追溯的 supersedes 证据链。

适用场景

解决思路

1. 先用 config({ key: 'content.dir' }) 读取内容目录，后续路径均相对该目录。
2. 兼容旧格式：把已有的 status: provisional/canonical 视为 draft/stable，把 sources: 中的字符串路径视为 source 资源，不要批量重写，新写入使用 OKF 格式。
3. 在任何写入前执行 STOP gate，向用户口头确认三件事：实际决策是什么（如“我们选了 Yjs 做 CRDT”，而非“Yjs 是一个选项”）、考虑并否决了哪些替代方案、团队采用的决策理由（不是你自己从来源重构的）。
4. 如果决策仍未定，不要整合，告知用户“研究仍是临时的，等团队决定后再回来整合”，然后停止。
5. 加载研究：用 exec("grep -rn <topic-keyword> <content-dir>") 查找先前研究，或用 exec("ls -A research") 列出研究目录，用 exec("cat <path>") 完整读取每篇研究文章。
6. 跟随每篇研究的 sources: frontmatter 列表，读取每一个被引用的来源文件。
7. 同时读取该主题已有的权威文章——若已存在，可能是更新而非新建。
8. 如果没有可整合的研究，停止；整合是提升而非创造，先做 /research-with-sources 技能。
9. 加载研究后再次确认决策：若研究发现未反驳的开放问题或被遗忘的替代方案，先暂停并与用户重新确认再写。
10. 边写边持久化：先创建文章骨架（frontmatter + 各标题），再逐节 edit 写入，不要把整篇综合内容留在上下文中一次性写出。
11. 保存位置：若项目使用三层生命周期（external-sources/ → research/ → articles/），存到 articles/ 下，主题宽泛时按子文件夹分组（如 articles/editor/crdt-architecture.md）；若项目已有权威文档布局（docs/、guides/ 等），按项目惯例存放；位置不明确时询问用户。
12. frontmatter 使用：title、description、type: article、status: stable、date: YYYY-MM-DD、tags（含 article、canonical、topic-tag）、supersedes（指向被整合的研究文章路径）。
13. 文章结构依次包含：Summary（一段话说清决策与原因）、Context（问题与约束）、Decision（直接陈述“我们选择了”，不用“我们推荐”）、Rationale（为何选此路径）、Trade-offs（放弃什么，围绕已选路径而非菜单式罗列）、Alternatives considered（其他选项及否决原因，链接到研究文章）、Implementation notes（关键文件、模式、坑）、Further reading（研究文章与外部来源链接）。
14. 正文中每个指代其他文档的名词短语都用标准 markdown 链接，不要写成纯文本。
15. 每个链接都必须可解析：只链接已存在的文档；若某概念应有独立页面但尚不存在，不要产生坏链——要么本次创建该页面，要么记录为跟踪任务（用宿主任务工具，没有就告知用户），并保留为纯文本。
16. 写完后用 exec("grep -rn <topic> <content-dir>") 找 2-3 个紧密相关的现有页面，从每页添加指向新文章的链接（通常放在 See also 或相关行内），让文章可通过反向链接被发现。
17. 在 Further reading 中链接来源与被取代的研究，方便读者追溯。
18. 在新文章 frontmatter 的 supersedes: 列表中指向被整合的研究文章，建立审计链。
19. 不要删除研究文章：编辑其 frontmatter，添加 status: deprecated 和 superseded_by: <新权威文章路径>。
20. 验证：文件存在于内容目录下所选路径；frontmatter 含 type: article 和 status: stable；列出了被取代的研究文章；研究文章已更新 status: deprecated 和 superseded_by 指针；exec("ls -A <target-dir>") 能看到新文件。

适用边界 · 注意事项

• 团队尚未真正做出决策时不要整合——产出的“权威”文章会谎报团队的理解状态，误导后续 agent。
• 尚未阅读底层来源时不要整合——产出会缺乏证据。
• 不要删除研究文章、不要逐字重写研究文字、不要跳过 supersedes / superseded_by 链接。