consolidate-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Consolidate — promote research into a canonical article

整理研究内容——将研究升级为规范文章

This skill is pack guidance. The platform
/open-knowledge
skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the procedure on top.

Promote existing research on a topic into a canonical article under

articles/

. Canonical, not provisional — the output is the source of truth for future agents, not a snapshot of uncertainty.

The content directory is the resolved

content.dir

— read it with

config({ key: 'content.dir' })

if you don't already know it. Paths below are relative to it.

本技能属于包内指导内容。平台的
/open-knowledge
技能（读写/预览/链接/锚定规则）仍管控所有Markdown操作——本技能是在此基础上叠加的流程规范。

将某一主题的现有研究内容升级为

articles/

目录下的规范文章。需为规范内容，而非临时内容——输出内容是未来Agent的权威信息来源，而非不确定性的快照。

内容目录为已解析的

content.dir

——若尚不明确，可通过

config({ key: 'content.dir' })

读取。以下路径均为相对于该目录的路径。

STOP gate: has a decision actually been made?

停止闸：是否已实际做出决策？

Consolidation is promotion, not creation. If the team hasn't decided, the resulting "canonical" article lies about the team's state of understanding — future agents read it, act on it, and the false certainty compounds.

Before any write, confirm out loud with the user:

What is the actual decision? (e.g., "We chose Yjs for CRDT" — not "Yjs is one option")
What alternatives were considered and rejected? (these go in "Alternatives considered," not as equals)
What's the rationale the team used? (not your reconstruction from sources)

If the decision is still open, do not consolidate. Tell the user: "The research is still provisional. When the team decides, come back and consolidate with the outcome." Then stop.

整理是升级，而非创建。如果团队尚未做出决策，生成的“规范”文章会误导团队的认知状态——未来Agent读取后会依此行动，这种虚假的确定性会不断放大。

在进行任何写入操作前，需向用户明确确认：

实际决策内容是什么？（例如：“我们选择Yjs作为CRDT方案”——而非“Yjs是可选方案之一”）
考虑过哪些替代方案并予以否决？（这些内容应放在“已考虑的替代方案”部分，而非与选定方案并列）
团队做出决策的依据是什么？（并非你从资料中重构的内容）

若决策仍未确定，请勿进行整理。告知用户：“当前研究仍为临时内容。待团队做出决策后，再返回并根据结果进行整理。”然后停止操作。

When to use this procedure

何时使用本流程

A team has made a decision after research and wants the outcome committed as canonical knowledge
You want to compact several provisional research notes into one authoritative article
A developer asks to "consolidate" or "finalize" the knowledge on a topic

Do NOT consolidate when:

The team has not actually decided (the output would be misleading — keep it as research)
You have not read the underlying sources (the output would lack evidence)

团队经研究后已做出决策，希望将结果作为规范知识留存
你需要将多篇临时研究笔记整合为一篇权威文章
开发者要求“整理”或“定稿”某一主题的知识

请勿在以下场景使用本流程：

团队尚未实际做出决策（输出内容会产生误导——应保留为研究内容）
你未阅读相关的底层资料（输出内容会缺乏证据支撑）

Principle: canonical, not provisional

原则：规范而非临时

A consolidated article is the source of truth. Agents reading it should not need to dig further for context — it should stand on its own. That means:

Clear, direct statements (no "tentative", no "initial findings")
Decisions stated as decisions, not options
Rationale explained so future readers understand the why
Trade-offs acknowledged but framed against the chosen path, not as a menu
Evidence linked but not the whole story — this article is the destination, not a trail

整理后的文章是权威信息来源。读取该文章的Agent无需进一步挖掘上下文——文章应独立完整。这意味着：

表述清晰直接（不含“暂定”“初步发现”等词汇）
决策内容需明确为已做出的决定，而非可选方案
解释决策依据，以便未来读者理解背后的原因
需承认取舍，但要围绕选定方案展开，而非罗列所有选项
需链接相关证据，但无需完整呈现——本文是最终结论，而非线索路径

Steps

步骤

1. Load the research + sources

1. 加载研究内容及资料

Locate research articles on this topic:

Use
```
exec("grep -rn <topic-keyword> <content-dir>")
```
to find prior research, or
```
exec("ls -A research")
```
if the project groups research in a known location
Read each research article fully via
```
exec("cat <path>")
```
(rich enrichment gives frontmatter + shadow-repo activity + project git history + backlinks)
Follow its
```
sources:
```
frontmatter list — read every referenced source file
Also read any existing canonical article on the topic — if one already exists, you may be updating it rather than creating a new one

If there is no research to consolidate, stop. Consolidation is promotion, not creation. Do the

/research-with-sources

skill first.

定位该主题的研究文章：

使用
```
exec("grep -rn <topic-keyword> <content-dir>")
```
查找过往研究内容，若项目将研究内容集中存放于已知位置，可使用
```
exec("ls -A research")
```
通过
```
exec("cat <path>")
```
完整阅读每篇研究文章（丰富的增强信息包含前置元数据、影子仓库活动、项目Git历史记录及反向链接）
跟进其
```
sources:
```
前置元数据列表——阅读所有引用的源文件
同时阅读该主题下已有的规范文章——若已存在，你可能需要更新它而非创建新文章

若无可整理的研究内容，停止操作。整理是升级，而非创建。请先使用

/research-with-sources

技能。

2. Re-confirm the decision

2. 再次确认决策

You already confirmed the decision at the STOP gate at the top. This step is a brief re-check after loading the research in Step 1 — occasionally the research surfaces something that makes the "decision" look less decided than the user initially claimed (an un-rebutted open question, an alternative they forgot about). If the loaded research reveals that, pause and re-confirm with the user before writing.

你已在顶部的停止闸环节确认过决策。本步骤是在步骤1加载研究内容后的简短复查——有时研究内容会揭示一些信息，让用户最初声称的“决策”看起来并不确定（例如未被反驳的开放性问题、用户遗忘的替代方案）。若加载的研究内容出现此类情况，请暂停操作并再次向用户确认决策，之后再进行写作。

3. Write the canonical article

3. 撰写规范文章

Persist as you go (MUST). For a large consolidation drawing on several research docs, create the article skeleton — frontmatter + the headings below — first, then

edit

each section in as you finish it; don't hold the whole synthesis in context for one final write. A rate limit or crash mid-synthesis then costs you one section, not the entire article. (The platform skill's Writing section carries this rule for all long-running work: the knowledge base is your checkpoint.)

Save inside the content directory. Path convention depends on the project:

If the project uses the three-layer lifecycle (
```
external-sources/
```
→
```
research/
```
→
```
articles/
```
), save under
```
articles/
```
, grouped by topic subfolder when the area is broad (e.g.,
```
articles/editor/crdt-architecture.md
```
)
If the project has an existing canonical-docs layout (
```
docs/
```
,
```
guides/
```
, etc.), save there in a location that matches the project's conventions
Ask the user when the canonical location is ambiguous

Frontmatter:

yaml

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

Structure:

markdown

undefined

必须边写边保存。若需整合多篇研究文档进行大规模整理，请先创建文章框架——前置元数据+以下标题，然后在完成每个部分后使用

edit

进行编辑；不要将所有整合内容放在内存中一次性完成最终写入。若中途出现速率限制或崩溃，仅会损失一个部分的内容，而非整篇文章。（平台技能的写作部分针对所有长期工作都有此规则：知识库是你的检查点。）

将文章保存至内容目录中。路径规则取决于项目：

若项目使用三层生命周期（
```
external-sources/
```
→
```
research/
```
→
```
articles/
```
），请保存至
```
articles/
```
目录下，若主题范围较广，可按主题子文件夹分组（例如：
```
articles/editor/crdt-architecture.md
```
）
若项目已有规范文档布局（
```
docs/
```
、
```
guides/
```
等），请按项目惯例保存至对应位置
若规范位置不明确，请询问用户

前置元数据：

yaml

---
title: 描述性标题
description: 本文内容的一行摘要
status: canonical
date: YYYY-MM-DD
tags:
  - 主题标签
supersedes:
  - <研究文章路径>.md
---

文章结构：

markdown

undefined

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.]

[如何在代码库中实现此方案——关键文件、模式、注意事项。]

延伸阅读

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

undefined

[链接至研究文章及外部资料，供希望了解决策过程的读者查阅。]

undefined

4. Link aggressively

4. 全面建立链接

Canonical articles are destinations — they should be linked heavily from everywhere they're relevant and link out to every related page themselves. Underlinked canonical articles lose most of their value.

Inside this article: every noun-phrase that names another document (other canonical articles, related research, external-source pages, sibling topics) should be a standard markdown link, not plain prose.
Every link must resolve. Only link to docs that exist. If you mention a concept that should have its own page but doesn't yet, do NOT emit a broken link — either create that page in this pass, or record it as a tracked task (your host's task tool; if the host has none, tell the user) and leave the mention as plain prose. A broken link is debt, not a to-do marker.
Update neighbors. After writing, find 2-3 closely-related existing pages (via
```
exec("grep -rn <topic> <content-dir>")
```
) and add a link to the new article from each — usually under a "See also" section or inline where the new article is relevant. This makes the article discoverable via backlinks, not just by remembering the path.
Link to the sources and superseded research from "Further reading" — readers who want the trail can follow.

规范文章是最终目的地——应在所有相关位置大量链接至本文，同时本文也应链接至所有相关页面。链接不足的规范文章会失去大部分价值。

本文内部： 所有指代其他文档的名词短语（其他规范文章、相关研究内容、外部资料页面、同类主题）均应使用标准Markdown链接，而非纯文本。
所有链接必须可解析。仅链接至已存在的文档。若提及的概念本应有对应的页面但尚未创建，请勿生成无效链接——要么在本次操作中创建该页面，要么将其记录为跟踪任务（使用宿主的任务工具；若宿主无相关工具，告知用户），并保留纯文本提及。无效链接是技术债务，而非待办标记。
更新相关页面。完成写作后，通过
```
exec("grep -rn <topic> <content-dir>")
```
找到2-3篇密切相关的现有页面，并在每篇页面中添加指向新文章的链接——通常放在“另请参阅”部分或新文章相关的内联位置。这样用户不仅可以通过路径找到文章，还可以通过反向链接发现它。
在“延伸阅读”部分链接至资料及被替代的研究内容——希望了解决策过程的读者可跟进这些链接。

5. Supersede the research

5. 标记替代关系

Add a

supersedes:

list in the new article's frontmatter pointing at the research article(s) it consolidates. This creates an audit trail.

Do NOT delete the research articles — they remain as historical context for how the decision was reached. Edit their frontmatter to add:

yaml

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

在新文章的前置元数据中添加

supersedes:

列表，指向其整合的研究文章。这将创建一条审计追踪链。

请勿删除研究文章——它们作为决策过程的历史上下文保留。编辑研究文章的前置元数据，添加：

yaml

superseded_by: <新规范文章路径>.md

6. Verify

6. 验证

File exists at the chosen path under the content directory
Has
```
status: canonical
```
frontmatter
Lists the research articles it supersedes
Research articles updated with
```
superseded_by
```
pointer
```
exec("ls -A <target-dir>")
```
shows the new file

文件已保存至内容目录下的选定路径
前置元数据包含
```
status: canonical
```
已列出其替代的研究文章
研究文章已更新
```
superseded_by
```
指向
```
exec("ls -A <target-dir>")
```
显示新文件已存在

Non-goals

非目标

Don't consolidate research that hasn't reached a decision — the article would misrepresent the team's actual state of understanding
Don't delete research articles — they are the trail; keep them with a
```
superseded_by
```
marker
Don't rewrite research prose verbatim — canonical articles have a different voice (direct, decided) than research (exploratory, provisional)
Don't skip the supersedes / superseded_by links — the audit trail matters for future readers

请勿整理未形成决策的研究内容——文章会误导团队的实际认知状态
请勿删除研究文章——它们是决策过程的线索；保留并添加
```
superseded_by
```
标记
请勿直接照搬研究内容的措辞——规范文章的表述风格（直接、确定）与研究内容（探索性、临时性）不同
请勿跳过
supersedes
/
superseded_by
链接——审计追踪链对未来读者至关重要

consolidate-notes

Original

Translation

Consolidate — promote research into a canonical article

整理研究内容——将研究升级为规范文章

STOP gate: has a decision actually been made?

停止闸：是否已实际做出决策？

When to use this procedure

何时使用本流程

Principle: canonical, not provisional

原则：规范而非临时

Steps

步骤

1. Load the research + sources

1. 加载研究内容及资料

2. Re-confirm the decision

2. 再次确认决策

3. Write the canonical article

3. 撰写规范文章

Summary

摘要

Context

背景

Decision

决策

Rationale

决策依据

Trade-offs

取舍

Alternatives considered

已考虑的替代方案

Implementation notes

实施说明

Further reading

延伸阅读

4. Link aggressively

4. 全面建立链接

5. Supersede the research

5. 标记替代关系

6. Verify

6. 验证

Non-goals

非目标