git:20260626.475d40c to git:20260714.837b640

34 added, 5 removed. Audit A to A.

---

name: vaultspec-research

description: Explore an unfamiliar problem and weigh options before committing. Use when unsure how to approach a complex feature, refactor, or bug.

---

# 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.

+ 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.

+ 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:** record every finding's source as a re-fetchable locator (URL,

- `file:line`, commit SHA, `package@version`, RFC number); ground code in a

- `<Reference>` via `vaultspec-code-research` and link it. Keep the artifact lean by

- pointing to sources, not reproducing them.

+ `file:line`, commit SHA, `package@version`, RFC number) and collect them in the

+ closing `## Sources` section; ground code in a `<Reference>` via

+ `vaultspec-code-research` and link it. Keep the artifact lean by pointing to sources,

+ not reproducing them.

+ ## Quality gate

+ The artifact is judged by decision value per token, not volume; it is re-read by agents

+ in every later pipeline phase, so every sentence must earn its place. Before persisting,

+ hold the document to this bar:

+ - **Answer-first.** The lead paragraph states the question, why it matters, and the

+ conclusion or recommendation; each finding opens with its claim, evidence after.

+ - **Locator-anchored.** Every non-obvious claim carries a re-fetchable locator (URL,

+ `file:line`, commit SHA, `package@version`, RFC number); a claim without one is an

+ opinion and is marked as such.

+ - **Comparative.** The real alternatives are named with why each was kept or rejected,

+ not a single advocated answer.

+ - **Specific.** Versions, dates, numbers, and concrete constraints are pinned; never "X

+ is popular" or "widely used."

+ - **Bounded and honest.** What was not investigated is stated; confidence and unknowns

+ are marked rather than certainty manufactured; general-knowledge claims not

+ re-verified are flagged.

+ - **Lean.** Sources are linked, never reproduced; no hedging boilerplate, no restated

+ prompt, no closing summary repeating the body. A sentence whose removal loses no

+ decision input is cut.

+ Dispatched researcher personas return findings held to 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.