git:20260714.78f2e42 to git:20260905.f755314

36 added, 90 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.

+ description: Ground a decision in evidence before it is made. Use when an ADR is warranted and the options have not been weighed on evidence already in the vault or the code.

---

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

+ # Research (vaultspec-research)

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

+ Produces a Research record: the evidence a later ADR decides on. Enter it when the

+ vaultspec sizing warrants an ADR and the options are not already weighed in the vault or

+ the code. A question this session can answer without new evidence is answered in the

+ conversation; if that answer then becomes an ADR, this record is written first, however

+ short. This skill terminates within one run.

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

+ ## Steps

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

+ - Ground per the `vaultspec-discovery` rule, decisions first: prior ADRs and research on

+ the feature, read whole. Link what already exists; do not restate it.

+ - Scaffold: `vaultspec-core vault add research --feature {feature}` (or the `create`

+ tool). Read `.vaultspec/templates/research.md`; its hint blocks fix the body shape:

+ answer-first lead, claim-first `## Findings`, closing `## Sources`.

+ - Research in this run, or dispatch the `vaultspec-adr-researcher` persona (and

+ `vaultspec-researcher` for parallel threads) with "Conduct research on `{topic}`", and

+ transfer the returned findings into the body without diluting their locators.

+ - When the decision needs grounding in real code, branch to `vaultspec-code-research`

+ for a Reference record and link it in `related:`.

+ - Fill every section this session; never leave or present an unfilled record.

+ - Verify with `vaultspec-core vault check all`.

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

+ Judged by decision value per token; later phases re-read this record.

- - **Back to refinement** -> without approval, prompt the user to refine goal and

- constraints, then re-run research.

+ - **Answer-first.** The lead states question, stakes, and conclusion; each finding opens

+ with its claim.

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

+ `file:line`, commit SHA, `package@version`, RFC); an unanchored claim is marked as

+ opinion.

+ - **Comparative and specific.** Alternatives named with why each was kept or rejected;

+ versions, dates, and numbers pinned.

+ - **Grounding, not deciding.** At most name the option the evidence favours and what the

+ ADR must settle. Decisions are recorded only in the ADR.

+ - **Bounded and lean.** Uninvestigated areas stated; link, do not copy; no hedging, no

+ restated prompt, no closing summary.

- ## Artifact linking

+ ## Next

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

+ Proceed to `vaultspec-adr`, in this run or the next; the ADR's approval covers the

+ findings, so this record needs no reply of its own. If the user faults the findings,

+ revise this record's body in place.