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.

research/

/consolidate-notes

content.dir

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

• Path A — Research article (DEFAULT): A persistent provisional article with an inline

  sources:

  frontmatter list pointing at raw sources captured via the ingest procedure. This is the default unless the user explicitly opts out.
• Path B — Direct answer: Findings delivered in conversation only. Requires explicit user request (e.g., "just tell me", "no doc needed", "quick answer").
• Path C — Update existing research: Surgical additions/corrections to an existing research article. Triggered when the user references an existing research doc or says "update/refresh/extend."

WebFetch

WebSearch

1. Step 0: Create workflow checkpoint tasks — ALWAYS the first action.
2. Step 1: Scan existing coverage + route — scan the content directory for prior work; classify coverage; present options before new research begins.
3. Step 2: Collaborative scoping — propose a research rubric. In Supervised mode, STOP and WAIT for user confirmation before any external fetch.
4. Step 3: Capture raw sources via ingest — preserve before analyzing.
5. Step 4: Read + analyze — third-party/external by default; first-party codebase only when the user explicitly requests.
6. Step 5: Write the research article — Path A only.
7. Step 6: Link aggressively + file valuable Q&A back.
8. Step 7: Validate — frontmatter, dead-links, sources alignment.
9. Step 8: Recap + follow-up directions.

• Default: external sources (web, open-source repos, papers, official APIs).
• Exception: if the user asks "research how our X compares to Y" or "include our codebase," include it — but clearly separate first-party observations from third-party findings in the article so a reader can distinguish externally-verifiable facts from organization-specific takes.

• Ingest each source the moment you fetch it (Step 3), one at a time — never fetch all sources and ingest them in a trailing batch. An ingested source survives a crash; a fetched-but-unwritten one does not.
• Create the article skeleton early and fill it section-by-section as you read (Steps 4-5), not in one final write at the end. After you analyze each source,

  edit

  its findings into the article before moving to the next. A crash after reading five of eight sources then leaves five sections safely in the KB; you resume by reading the partial article back, not by re-running the whole sweep.

1. exec("grep -rln <topic-keyword> <content-dir>")

   — returns matching files with frontmatter enrichment so you can judge relevance without opening each.

2. exec("ls -A <content-dir>")

   — surfaces folder layout and most-recent-updated doc per subdir.
3. For the 1-3 most promising candidates,

   exec("cat <path>")

   — returns full doc + frontmatter + backlinks + recent shadow-repo activity.

"We already have research on this in

<path>

. Here's what it found: [2-4 key findings]. Options: (1) use as-is, (2) verify / refresh (article is from [date]), (3) extend on [specific dimension], (4) new angle if this is a different framing."

"We have related research in

<path>

covering [scope]. Your question about [topic] isn't directly answered but it's a natural extension. Options: (1) extend existing via Path C, (2) start new article via Path A. I'd recommend [1 or 2] because [reason]."

• Do not skip the scan. Even 30 seconds of grep + cat prevents duplicate research AND gives the user context on what's already known.
• Bias toward extending (Path C) when topics are semantically coherent — one comprehensive article beats two overlapping ones.
• Bias toward new (Path A) when framing, audience, or primary question differs materially.

1. [Dimension 1]
2. [Dimension 2] ...

• [Source 1 — why it's relevant]
• [Source 2 — why it's relevant] ...

<existing-article>

undefined

• If the original topic is vague ("research LLM agents"), narrow it before fetching: "What specific agents? For what decision? Over what time horizon?"
• If the topic is itself a URL, treat that URL as the anchor and widen to 2-4 adjacent authoritative sources.
• Name the decision this research informs. Research without a decision context meanders.
• Do not over-specify the rubric — the user can adjust. Propose, don't prescribe.

/open-knowledge

references/ingest-and-sources.md

• Don't skip ingest. Raw preservation separates capture from interpretation and makes research reproducible. An article without preserved sources is just opinion; an article with preserved sources is a trail someone else can follow.
• If a fetch fails for a source you specifically need, stop and ask the user to paste it — don't silently drop it. Write-time fabrication of missing evidence is the biggest failure mode.
• If a fetch returns an obvious summary instead of the raw bytes (some LLM-backed fetch tools do this), note it and try a raw alternative (

  curl -sL <url>

  , or ask the user to paste).

• Existing canonical articles on the topic —

  exec("cat <path>")

  (returns frontmatter + backlinks + shadow-repo activity).
• Prior research on adjacent topics — same:

  exec("cat <path>")

  for OpenKnowledge markdown.
• Relevant source code — ONLY if the user asked for first-party analysis. Use native

  Read

  for

  .ts

  /

  .js

  / etc.;

  exec

  for in-scope

  .md

  /

  .mdx

  .
• Project context — wherever the project keeps design material.

• Key claims and their evidence — every claim needs a source you can point at
• Trade-offs between options
• Contradictions between sources — these are often the most valuable part of the article
• Unknowns and open questions — the boundary of what you know
• Relevance to the specific decision at hand

edit

exec("cat <path>")

• If the project adopted the three-layer lifecycle (

  external-sources/

  →

  research/

  →

  articles/

  ), save under

  research/<slug>.md

  .
• If the project has an existing docs/reports/specs layout, match it.
• Large topics warrant a subfolder:

  research/<topic>/<subtopic>.md

  .

crdt-alternatives-for-editor.md

llm-wikis-and-knowledge-bases.md

• Pros — with evidence links
• Cons — with evidence links
• Evidence: Source A, Source B

• Provisional, not canonical. Use "tentative", "initial findings", "based on current understanding."
• Do NOT write as if it were canonical — that's misleading. Canonicality is the

  /consolidate-notes

  skill's job, after decisions land.
• Explicit about uncertainty. Research is the layer where uncertainty is allowed to live.

• Every noun-phrase that names another document is a link. Use standard markdown:

  [text](./relative/path.md)

  .
• Link sources inline where you cite them, not just in the frontmatter

  sources:

  list:

  According to [LLM Agents](./external-sources/llm-agents.md)...

  is stronger than a bare

  sources:

  entry.
• Cross-link sibling research: if an adjacent topic has its own research doc, link it under "Open questions" or inline. Readers following one thread should find the others.
• After writing, update 1-2 closely-related existing pages to link back to this research (usually under "Further reading" or "See also"). This is how the research becomes discoverable via backlinks.
• Never wrap links in backticks; never use HTML anchors — matches the platform skill's linking rules.

• Short filename:

  what-does-X-mean.md

  ,

  how-does-Y-work.md

• Include the same

  sources:

  frontmatter
• Link the answer from this research doc under "Further reading"
• Answers too small to justify a separate file stay in chat; don't fragment

• File exists at the chosen path under the content directory
• Frontmatter has

  title

  ,

  description

  ,

  status: provisional

  ,

  date

  , and a

  sources:

  list

• exec("ls -A <dir>")

  lists the new file with frontmatter enrichment

• links({ kind: 'dead', sourceDocNames: ['<path-without-ext>'] })

  returns clean — zero dead links (fix or remove every one)
• Every factual claim in Findings cites a source inline
• Linked source files from Step 3 all exist (broken source links → ingest went wrong somewhere)
• At least 1-2 neighbor docs now link to this research (per Step 6's "After writing, update ..." rule)

• [Finding 1 — with source]
• [Finding 2 — with source]
• [Key trade-off / contradiction surfaced]
• [1-2 open questions that remain]

1. [Direction 1 — what would it investigate?]
2. [Direction 2 — what would it investigate?]
3. [Direction 3 — what would it investigate?]

Follow-ups should be **external-source investigations** — not actions on the user's codebase (those belong in a spec, not more research). Each direction should be a standalone topic someone could later research.

In headless mode, write the recap into the research article's "Further reading" section rather than prompting interactively.

---

• Don't promote to a canonical article. That's the

  /consolidate-notes

  skill's job after a decision actually lands. Premature canonicalization buries uncertainty and misleads future readers.
• Don't hide uncertainty. Research is the layer where "we don't know yet" is acceptable prose. Say it explicitly.
• Don't skip ingest. Always capture raw sources first, then analyze. An article without preserved sources is opinion.
• Don't skip the Step 1 scan. Duplicate research wastes the user's time AND misses chances to extend prior work.
• Don't skip the scoping gate in Supervised mode. The user's rubric shapes everything downstream; you cannot recover a wrong-scope article cheaply.
• Don't mix first-party codebase analysis into the article unless asked. Findings drift from factual synthesis to opinion when you do.
• Don't overwrite existing research silently. If the topic was researched before, either iterate (Path C) or create a clearly-named successor (

  crdt-alternatives-2.md

  ) and mark the old one as superseded.