Vaultspec research

Research and brainstorm skill (vaultspec-research)

Use this skill:

• Before implementing non-trivial features.
• When unsure about major design decisions.
• Before refactors with unclear scope.
• Before debugging complex issues.
• When you need user input on design options.

Announce at start: "I'm using the vaultspec-research skill to conduct structured research and brainstorming."

Required steps

• Ground in existing intent first. Begin by grounding via semantic search - the fastest, cheapest way to surface what the project already decided and built. Follow the validated sequence: locate, read whole, confirm. Retrieve governing decisions with vaultspec-rag search "<intent>" --type vault --doc-type adr (the directed ADR filter, sharper than catch-all --type vault), prior exploration with vaultspec-rag search "<intent>" --type vault (or --doc-type research), and the implementation sites with vaultspec-rag search "<intent>" --type code. Lean on vaultspec-core status and vaultspec-core vault list - first-class for orientation - to map in-flight plans and records. Read what this surfaces in full and check for overlap before adding new findings; round out decision recall by listing .vault/adr/ and filtering by feature. Where vaultspec-rag is not installed, the vaultspec-core discovery verbs and grep carry the same sequence.

• Read and use the template at .vaultspec/templates/research.md; its embedded hint blocks govern the body structure: an answer-first lead paragraph, claim-first ## Findings subsections, and a closing ## Sources section.

• Load the vaultspec-adr-researcher agent persona for focused work. When the task benefits from multiple researchers, load the generic vaultspec-researcher agent persona for the additional research threads and coordinate them through the host environment. Instruct each researcher to "Conduct research on {topic}." and write the returned findings into the scaffolded document's body.

• Persist findings: scaffold the research artifact with vaultspec-core vault add research --feature {feature}, then author the findings as body prose in the scaffolded file. The CLI owns the filename (.vault/research/yyyy-mm-dd-{feature}-research.md) and the frontmatter; never hand-write either. The full frontmatter schema is defined in the vaultspec rule; verify after scaffolding with vaultspec-core vault check all rather than hand-editing frontmatter. A scaffold left with its hint text, an unfilled {topic}, or an empty Findings section is not research - fill every section in the same session or do not create the document.

• Persist sources: every finding's source is a re-fetchable locator (URL, file:line, commit SHA, package@version, RFC number), cited inline and collected once in the closing ## Sources section; ground code in a <Reference> via vaultspec-code-research and link it.

Quality gate

Judged by decision value per token; agents re-read the artifact in every later phase. Before persisting, hold the document to this bar:

• Answer-first. Lead states question, stakes, and conclusion; each finding opens with its claim, evidence after.
• Locator-anchored. Every non-obvious claim carries a re-fetchable locator; an unanchored claim is marked as opinion.
• Comparative. Alternatives named, with why each was kept or rejected.
• Specific. Versions, dates, and numbers pinned; never "popular" or "widely used."
• Deduplicated. Each fact stated once. What a related vault document already records is linked, not restated; what an earlier section establishes is not repeated.
• Grounding, not deciding. Frame options, evidence, and trade-offs; at most name the option the evidence favors and what the <ADR> must settle. Decisions are recorded only in the <ADR>.
• Bounded. Uninvestigated areas stated; unverified general-knowledge claims flagged.
• Lean. Link, do not copy; no hedging boilerplate, no restated prompt, no closing summary.

Dispatched researcher findings meet the same bar; transfer them into the scaffolded body without diluting the locators.

Workflow

Research is the upstream precursor for a feature: it produces <Research> grounding for a decision, not an implementation. From here the work branches:

• Forward to the decision -> on user approval, proceed with the vaultspec-adr skill to create and persist the <ADR> the research supports.

• Out to grounding -> when the decision needs grounding in real source code, reference implementations, or library docs, branch to the vaultspec-code-research skill (which can dispatch the vaultspec-reference-auditor agent) to produce a <Reference>, then fold its findings back into the research or ADR.

• Back to refinement -> without approval, prompt the user to refine goal and constraints, then re-run research.

Artifact linking

• Persisted documents reference each other with quoted '[[wiki-links]]' in the related: frontmatter field.
• DO NOT use @ref style links.
• DO NOT use [label](path) style links for internal wiki pages.