/consolidate

name: consolidate-notes
description: "Promote existing research into a stable-status canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research-with-sources` skill."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by `ok seed --pack knowledge-base` (`ok-beta` for Beta)."
type: Document
metadata:
  pack: "knowledge-base"
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"

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.

**Legacy reads:** Existing research and articles may use `status: provisional` / `canonical`, and existing `sources:` may contain string paths. Treat those as draft / stable and source resources. Do not mass-rewrite them; new writes use the OKF forms below.

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.

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

Steps

1. Load the research + sources

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.

2. Re-confirm the decision

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.

3. Write the canonical article

**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:

---
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:
  - <