query-research-vault

name

query-research-vault

description

Answer and research questions against a configured Obsidian research vault with vault-first evidence tracing, explicit uncertainty, controlled web fallback, and guarded live-vault integration. Use when a user asks to query a research vault; requests explanation, summarization, comparison, proofchecking, method validation, or academic writing from local evidence; supplies a Mode/Task/Question header; or asks to research unresolved gaps and integrate accepted evidence.

Query Research Vault

Required startup

1. Read references/vault-query-preamble.md completely. Treat its evidence, truth, citation, research, privacy, and integration rules as mandatory.

2. Parse the optional query header. If absent, use:

   Mode: ask-before-web
   Task: explain
   Question: <the user's complete request>
   

   Default only missing fields in a partial header. If an explicitly supplied value is invalid, ask for correction without browsing or writing.

3. Set the web-authorization gate before using an internet-capable tool:

   • allow web access for research-and-integrate;
   • allow it after the user explicitly approves research, including approval already stated in an unprefixed request;
   • otherwise deny it.

   During an initial ask-before-web pass, do not search, open, click, fetch, or resolve an external page, paper, DOI, documentation site, or API. Do not fill current evidence gaps from model memory. Treat external URLs in vault notes as unverified leads until approval.

4. Set SKILL_ROOT to this skill directory and resolve the vault from the caller's working directory:

   python3 "$SKILL_ROOT/scripts/resolve_vault.py" --start "$PWD"
   

   The resolver honors command-line overrides, RESEARCH_* environment variables, the file named by RESEARCH_VAULT_CONFIG, the closest .research-vault.json, and config/runtime.local.json, in that precedence order. Read references/vault-contract.md if discovery or configuration fails. Never substitute another vault after an explicit configuration fails.

5. Read <project_root>/AGENTS.md when it exists and obey it. Treat the resolved vault_root, project_root, project_path, vault_name, and kind as authoritative for this invocation.

6. Read references/obsidian-operations.md before vault operations. Use its filesystem, Obsidian Markdown, CLI, Bases, and write-safety rules without requiring another installed skill.

7. When the resolver reports kind: live, run the preflight on every invocation before reading through Obsidian:

   python3 "$SKILL_ROOT/scripts/ensure_obsidian.py" --start "$PWD"
   

   The helper probes the configured vault and, on Linux when enabled, can launch Obsidian on an invisible Xvfb display. If it fails, a read-only answer may continue through bounded filesystem inspection, but live integration and Base-dependent QA are blocked. Report the exact error. For kind: snapshot, do not launch Obsidian.

8. Read Project.md, README.md, Concept Index.md, and research-state.yaml from the resolved project root before routing the question.

Mode contract

Mode	Web access	Vault writes
vault-only	Never	None unless the user separately requests an edit
ask-before-web	Search the vault first. If a material gap remains, identify it and request approval before any web call.	None unless later approval explicitly includes integration
research-and-integrate	Research only unresolved gaps without another confirmation.	Integrate accepted evidence only when the resolver returns kind: live, writable: true, and integration_allowed: true.

An explicit header controls the workflow. Without a header, direct language that already authorizes external research satisfies the web gate; integration still requires clear authorization to update the vault. Higher-priority safety and tool rules always apply.

In ask-before-web, answer the supported portion before requesting approval. Cite only local vault evidence in that initial response. Name the missing evidence and proposed source types. If the vault fully answers the question, do not request web access.

In research-and-integrate, do not browse merely to decorate an already supported answer. Separate external evidence from prior vault evidence until integration and QA finish. Never upload a vault file, note excerpt, source PDF, or unpublished identifier unless the user explicitly authorizes that disclosure.

Task contract

• explain: answer directly, distinguish consensus from project interpretation, and add a project consequence only when relevant.
• summarize: preserve the source task, data type, population, targets, method, results, negative evidence, and limitations.
• compare: use one comparison frame; flag non-comparable data types, targets, splits, metrics, or evidence strength.
• proofcheck: decompose the statement into atomic claims and return a verdict, strongest support, counterevidence, and boundary for each.
• validate: assess defensibility, leakage and confounds, required controls, failure modes, and the smallest decisive experiments.
• academic-writing: produce citation-ready prose grounded in traced evidence; preserve qualifications and never invent bibliographic facts or citations.

Combine task behaviors only when the request needs more than one. Do not let the task label weaken the selected mode's web boundary.

Vault-first workflow

1. Route from the four startup files into relevant synthesis, report-bank, matrix, concept, methodology, or paper-note files.

2. Search for the user's terminology and likely synonyms. After a successful live preflight, prefer targeted commands with the resolved values:

   obsidian vault="$VAULT_NAME" search query="<terms>" path="$PROJECT_PATH" limit=50
   obsidian vault="$VAULT_NAME" read path="$PROJECT_PATH/<path>"
   obsidian vault="$VAULT_NAME" backlinks path="$PROJECT_PATH/<path>"
   

   For snapshots or a documented preflight failure, use the bundled search helper or bounded filesystem reads:

   python3 "$SKILL_ROOT/scripts/search_vault.py" --start "$PWD" --query "<terms>"
   

3. Trace material claims down from synthesis to canonical paper notes and PDF Markdown. Check extraction reports before trusting flattened equations, tables, figures, or page order. Use a real original PDF for page-sensitive verification; never treat an export placeholder as evidence.

4. Search for counterevidence, disagreements, open questions, and scope mismatches before concluding.

5. Cite every material factual claim with the strongest available vault source and label inference as inference.

Authorized external research

After the web gate passes, use the host's available research and browsing tools. Follow the source hierarchy and acceptance checks in the preamble. For technical questions, rely on primary papers, official specifications, and official documentation rather than secondary tutorials.

Accept evidence only after verifying canonical identity and status, direct relevance to the gap, support for the exact claim, methodological scope, and duplication against the vault. Acceptance is an evidence-quality gate, not another confirmation step in research-and-integrate mode.

Live-vault integration

Integrate automatically only when the resolver returns kind: live, writable: true, and integration_allowed: true, the selected mode is research-and-integrate, and the user has authorized vault updates. A writable snapshot, export, temporary tree, or example fixture is not a live write target.

Before editing, read the target file immediately and preserve useful analysis. Use Obsidian Markdown and wikilinks. For a new or replaced PDF extraction, use an installed high-fidelity PDF conversion workflow and validate it against the original PDF. If no suitable converter is available, do not create a low-confidence extraction; report the intake blocker and provide a proposed change manifest instead.

Update every materially affected note, backlink, index, synthesis, state, log, changelog, bibliography, inventory, and human-facing QA file required by the preamble and the vault's conventions.

After editing:

1. run validate_vault.py with the same runtime configuration;
2. validate YAML and any Bases;
3. verify new and affected links and backlinks;
4. check duplicate sources and identifiers;
5. verify extraction quality against the original PDF when a paper was added;
6. run residue and stale-state checks required by the vault;
7. run Obsidian CLI and Base checks; if contact is lost, rerun the preflight once and treat a second failure as a QA blocker;
8. state exactly what changed and what remains unresolved.

Do not modify a separate code repository while integrating research notes. If the live vault is absent, read-only, or not confidently identified, do not claim integration; provide replacement files or a patch bundle with a change manifest.

Response shape

Use all four headings from the preamble for every substantial answer unless the user requests another format. For an initial ask-before-web response, cite only local vault evidence; put unverified gaps in Confidence and limitations, include local files in Sources used, then end with Approval needed naming the proposed external searches. Do not include externally verified findings before approval. For integrations, add a short Vault changes section listing changed files and QA results.