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.