| name | research-vault |
| version | 0.1.1 |
| description | Research a topic and file it into an Obsidian-style Markdown "thinking vault" as an isolated, grounded, interlinked wiki branch — the EMBED phase: gather cited facts and structure them into neutral, descriptive notes (no verdicts). Use this whenever the user wants to research / investigate / look into / gather / "read up on" a subject and KEEP the result, especially when a vault CLAUDE.md is present, or when they say "research X", "spin up a wiki/branch on Y", "add notes on Z to the vault", "gather what's known about…", "ground this topic", or "set up a research vault". Prefer this over a plain chat answer whenever the research should be filed and kept, not just spoken. This skill only gathers and wikifies; evaluating the corpus or drawing a recommendation is the separate analyze-vault skill, and charts/pages are the separate vault-artifact skill — do not do those here. |
Research Vault — the EMBED phase
Turn a research request into a self-contained, grounded, interlinked wiki branch. This skill
does one job: gather cited facts and structure them into neutral notes. It deliberately does
not form a verdict or build visuals — those are separate, later phases (analyze-vault,
vault-artifact) that this skill knows nothing about. They compose only through the vault's files
and gates, which the vault's CLAUDE.md orchestrates.
Why the boundary matters
The vault's whole value is that a reader can tell established fact from someone's judgment.
If research notes smuggle in recommendations, that line blurs and the vault becomes just another
pile of opinions. So here you stay descriptive: lay out what is known, cite it, and stop. The
moment you catch yourself writing "so the best option is…", that belongs in an analysis, not here.
Step 0 — Locate or bootstrap the vault, and honor its CLAUDE.md
- Look for a vault: a
CLAUDE.md describing a thinking vault, plus Home.md / _templates/.
Usually the current working directory.
- If a vault
CLAUDE.md exists, it wins. Read it and follow its conventions over anything
here — the user may have tuned frontmatter, naming, or the pipeline. Defer to it.
- If there's no vault, scaffold one (a vault can live in any folder — drop it wherever
you like):
${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md → <vault>/CLAUDE.md${CLAUDE_PLUGIN_ROOT}/templates/* (moc, note, grounding, analysis) → <vault>/_templates/${CLAUDE_PLUGIN_ROOT}/templates/Home.md → <vault>/Home.md- create an empty
<vault>/.research-vault sentinel — this is what marks the folder as a
vault so the plugin's Stop hook can find it (drop-anywhere detection, no false positives).
Then tell the user a new vault was set up, and proceed.
- The verification gates are hosted in the plugin (
${CLAUDE_PLUGIN_ROOT}/gates/), not copied
into the vault — so every vault shares one canonical, updatable copy. Nothing to install per
vault beyond the sentinel above. (Bootstrapping an existing pre-praxisflux vault? Just add the
.research-vault sentinel; leave any legacy _scripts/ in place, it is no longer used.)
The embed workflow
1. Place it
Extend an existing branch or start a new one. New → create <Topic>/ (folder in
Title-Case-With-Hyphens) and its MOC <Topic>/<Topic>.md from _templates/moc.md.
2. Capture the brief (only when the request carries constraints)
If the user handed you facts, filters, a budget, or current state — not just "tell me about X" —
write Brief-and-Assumptions.md first: restate the requirements verbatim, then document your
assumptions and flag ambiguities as open questions. This makes silent guesses visible so the
user can correct course early. Skip it for a purely open-ended explore.
3. Seed the grounding
Produce <Topic>/_grounding.md (type: source) from _templates/grounding.md — the cited,
source-of-truth research pass. Keep it factual and close to verbatim; conclusions come later.
- Primary path: run the
deep-research skill on a scoped question; save its report verbatim.
- Fallback (important): the
deep-research harness sometimes fails on an internal error. Do
not get stuck retrying it — fall back to a direct WebSearch fan-out (6–10 parallel
searches across the distinct angles of the question), then synthesize into _grounding.md with
a real Sources list of URLs. Note which method you used.
- Small extension of an already-grounded branch → skip the heavy pass; do a few targeted searches.
4. Structure the knowledge (neutral notes)
Write the MOC and supporting notes from _templates/note.md. Organize what is known: how things
work, how the pieces relate, the established numbers — each claim citing into _grounding.md.
Split into multiple notes when one would sprawl; keep each focused. Fill the MOC's Scope and
What is known. Leave the Analyses section empty — that's the next phase's job.
5. Wire the branch
MOC lists every note under Notes; related: links set (in-folder only); updated: dates
current; add/refresh the topic's one-line entry in Home.md (the trunk).
6. GATE — verify the branch
Run the branch gate; it must pass before you're done:
node ${CLAUDE_PLUGIN_ROOT}/gates/cli.mjs branch <vault> <Topic>
It checks the MOC, the grounding file, frontmatter, and isolation (no cross-branch/broken links).
Fix anything it reports. A passing branch is what makes the analyze phase possible.
Handing off
When the branch is green, tell the user what you gathered and any open questions — and that they
can analyze it (evaluate / get a recommendation) as a separate step whenever they want. Don't
evaluate it yourself here.
Bundled resources
${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md — the vault orchestrator (planted on bootstrap).${CLAUDE_PLUGIN_ROOT}/templates/ — moc, note, grounding, analysis, Home.${CLAUDE_PLUGIN_ROOT}/gates/ — the Node gates (cli.mjs branch|analysis|artifact), shared by
all three phases and enforced by the plugin's Stop hook. Plugin-hosted; never copied per-vault.
