consolidate-notes

整合——将研究提升为权威文章

此技能是知识包指南。平台的 /open-knowledge 技能（读取／写入／预览／链接／依据规则）仍适用于所有 Markdown 操作；本技能在此基础上叠加流程。

将某个主题的现有研究提升为 articles/ 下的权威文章。权威，而非暂定——输出是未来 Agent 的事实来源，而不是对不确定性的快照。

内容目录是解析后的 content.dir——如果你还不知道该目录，请使用 config({ key: 'content.dir' }) 读取。以下路径均相对于该目录。

**读取旧格式：**现有研究和文章可能使用 status: provisional / canonical，现有的 sources: 也可能包含字符串路径。将它们视为草稿／稳定内容和来源资源。不要批量重写；新写入使用以下 OKF 格式。

停止关卡：是否真的已经作出决定？

整合是提升，而非创建。如果团队尚未作出决定，生成的“权威”文章就会歪曲团队当前的理解状态——未来的 Agent 会阅读并据此行动，而这种虚假的确定性会不断累积。

在进行任何写入之前，先向用户明确确认：

• 实际决定是什么？（例如，“我们选择了 Yjs 作为 CRDT”——而不是“Yjs 是一个选项”）
• 考虑并否决了哪些替代方案？（这些内容应放在“考虑过的替代方案”中，而不是与选定方案并列）
• 团队采用了什么理由？（不是你根据来源自行推断的理由）

如果决定仍未敲定，不要进行整合。告诉用户：“这项研究仍是暂定的。等团队作出决定后，再回来根据结果进行整合。”然后停止。

何时使用此流程

• 团队经过研究后已作出决定，并希望将结果作为权威知识提交
• 你想将多篇暂定研究笔记整合成一篇权威文章
• 开发者要求对某个主题的知识进行“整合”或“定稿”

以下情况不要进行整合：

• 团队实际上尚未作出决定（输出会造成误导——应将其保留为研究内容）
• 你尚未阅读底层来源（输出将缺乏证据）

原则：权威，而非暂定

整合后的文章是事实来源。阅读文章的 Agent 不应再需要进一步查找背景信息——文章本身应能自成一体。这意味着：

• 陈述清晰、直接（不使用“暂定”“初步发现”等表述）
• 将决定表述为决定，而非选项
• 解释理由，让未来的读者理解缘由
• 承认权衡，但应以选定方案为基准进行说明，而不是将其列成菜单
• 链接证据，但不要让证据成为全文——这篇文章是目的地，而非路径

步骤

1. 加载研究和来源

查找该主题的研究文章：

• 使用 exec("grep -rn <topic-keyword> <content-dir>") 查找先前的研究；如果项目将研究归档在已知位置，则使用 exec("ls -A research")
• 使用 exec("cat <path>") 完整阅读每篇研究文章（丰富增强功能会提供 frontmatter、影子仓库活动、项目 Git 历史和反向链接）
• 查看其 sources: frontmatter 列表，并读取其中引用的每个源文件
• 同时阅读该主题已有的权威文章——如果已经存在，你可以对其进行更新，而不是新建一篇

如果没有可整合的研究，请停止。整合是提升，而非创建。请先执行 /research-with-sources 技能。

2. 再次确认决定

你已在上方的停止关卡确认过决定。本步骤是在加载第 1 步的研究后进行简短复核——有时研究会揭示某些情况，表明这项“决定”并不像用户最初所说的那样已经敲定（例如，存在尚未回应的开放问题，或用户忘记了某个替代方案）。如果加载的研究揭示了这类情况，请暂停，并在写入前再次向用户确认。

3. 撰写权威文章

随写随保存（必须）。 如果要整合多份研究文档，请先创建文章骨架——包括 frontmatter 和下方标题——然后每完成一个章节，就用 edit 编辑该章节；不要把整个综合内容都留在上下文中，等最后一次性写入。这样一来，即使遇到速率限制或中途崩溃，也只会损失一个章节，而不是整篇文章。（平台技能的 Writing 部分将此规则应用于所有长时间运行的工作：知识库就是你的检查点。）

保存到内容目录中。路径约定取决于项目：

• 如果项目采用三层生命周期（external-sources/ → research/ → articles/），请保存到 articles/ 下；如果主题领域较广，可按主题放入子目录（例如 articles/editor/crdt-architecture.md）
• 如果项目已有规范文档布局（docs/、guides/ 等），请按照项目约定保存到合适的位置
• 如果规范位置不明确，请询问用户

Frontmatter：

---
title: Descriptive title
description: One-line summary of what this article covers
type: article
status: stable
date: YYYY-MM-DD
tags:
  - article
  - canonical
  - topic-tag
supersedes:
  - <path-to-research-article>.md
---

结构：

## Summary

[One paragraph: what the decision is and why. A reader who reads only this paragraph should know the outcome.]

## Context

[What problem does this solve? What constraints shaped the decision?]

## Decision

[The chosen approach, stated directly. Not "we recommend" — "we chose".]

## Rationale

[Why this path over alternatives. Grounded in the constraints from Context.]

## Trade-offs

[What we gave up by choosing this path. Frame against the chosen decision, not as a menu.]

## Alternatives considered

[Briefly: what else was on the table, why it was rejected. Link to the research article for deeper analysis.]

## Implementation notes

[How this gets realized in the codebase — key files, patterns, gotchas.]

## Further reading

[Links to research articles and external sources for readers who want the trail.]

4. 广泛添加链接

权威文章是内容的落脚点——凡是相关的地方，都应大量链接到它们；它们自身也应链接到所有相关页面。权威文章如果链接不足，其大部分价值就会付诸东流。

• 在本文中： 所有指向其他文档的名词短语（其他权威文章、相关研究、外部来源页面、相关主题）都应使用标准 Markdown 链接，而不是纯文本。
• 每个链接都必须有效。 只链接到确实存在的文档。如果你提到的概念应该有自己的页面，但目前还没有，不要生成失效链接——可以在本次工作中创建该页面，或将其记录为待办任务（使用宿主提供的任务工具；如果宿主没有任务工具，请告知用户），并将该提及保留为纯文本。失效链接是债务，不是待办标记。
• 更新相关页面。 写完后，通过 exec("grep -rn <topic> <content-dir>") 找出 2–3 个密切相关的现有页面，并从每个页面添加指向新文章的链接——通常放在“另请参阅”部分，或在相关内容处行内添加。这样读者就能通过反向链接发现文章，而不必记住路径。
• 在“延伸阅读”中链接到来源和已被取代的研究文档，方便读者追溯。

5. 标记研究文档已被取代

在新文章的 frontmatter 中添加 supersedes: 列表，指向它整合的研究文章。这将形成审计追踪。

不要删除研究文章——它们是决策过程的历史记录。请编辑其 frontmatter，添加：

status: deprecated
superseded_by: <path-to-new-canonical-article>.md

6. 验证

• 文件存在于内容目录下选定的路径
• frontmatter 中包含 type: article 和 status: stable
• 列出了被取代的研究文章
• 研究文章已更新为 status: deprecated，并包含 superseded_by 指针
• exec("ls -A <target-dir>") 显示新文件

非目标

• 不要整合尚未得出决策的研究——否则文章会歪曲团队当前的实际认知
• 不要删除研究文章——它们是过程记录；请保留并添加 superseded_by 标记
• 不要逐字改写研究内容——权威文章的语气（直接、明确）与研究文档（探索性、暂定）不同
• 不要省略 supersedes / superseded_by 链接——这份审计追踪对未来的读者很重要