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 "" --type vault --doc-type adr (the directed ADR filter, sharper than catch-all --type vault), prior exploration with vaultspec-rag search "" --type vault (or --doc-type research), and the implementation sites with vaultspec-rag search "" --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 ` 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 ` must settle. Decisions are recorded only in the `.

• 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 `` 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 `` 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 ``, 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nevenincs
• Source: nevenincs/vaultspec-core
• License: MIT
• Homepage: https://neve.md/vaultspec

Install and usage instructions live in the source repository linked above.