consolidate-notes

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:
  - <path-to-research-article>.md
---

Structure:

## 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. Link aggressively

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.

5. Supersede the research

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:

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

6. Verify

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

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