vault-query

name	vault-query
description	Karpathy-style vault query and synthesis system. Reads index.md to locate articles, synthesizes answers from multiple sources, and optionally writes high-value results back as new notes. Triggers: "/vault-query", "search vault", "find in notes", "query knowledge base"
allowed-tools	["Glob","Grep","Read","Write","Edit","Bash(open *)","Bash(ls *)","AskUserQuestion"]

Vault Query — Karpathy-Style Knowledge Synthesis

Based on the "compile, don't retrieve" philosophy: look up the index first, read full text to synthesize, write back high-value answers.

Workflow

Step 1: Environment Detection & Query Parsing

1a. Detect vault root — follow ../../_shared/common-steps.md "Vault Detection" section.

1b. Parse user query intent:

Extract from user input:

• query: core question or keywords
• scope: whether a directory scope was specified (e.g., user mentions a topic that maps to a configured directory)
• depth: simple lookup ("which article covers X") vs deep synthesis ("compile everything about X")

Step 2: Index Lookup

2a. Read index.md:

Read("$VAULT_ROOT/index.md")

Scan all entries in index.md — titles, summaries, and tags — to find candidate articles related to the query (typically 3-8).

2b. Supplementary search:

index.md may miss content. Use Grep to supplement:

Grep("{keyword}", path="$VAULT_ROOT", glob="**/*.md")

Exclude results from .claude/, .git/, reviews/, index.md.

2c. Determine reading list:

Merge index lookup and Grep results, sort by relevance, finalize the list of articles to read in full.

Step 3: Deep Read & Synthesis

3a. Read relevant articles in full:

For each article on the reading list, use Read to get full text. Read in parallel for efficiency.

3b. Synthesize the answer:

Choose synthesis mode based on depth:

• Simple lookup: list relevant articles and their key points, point the user to read directly
• Deep synthesis:
  1. Extract key information from multiple articles
  2. Integrate into a complete knowledge picture, citing sources (see [[article-name]])
  3. Surface connections, contradictions, or complementary relationships between articles
  4. Identify knowledge gaps ("no article covers aspect Y of topic X")

Step 4: Write-Back Decision

After synthesizing, evaluate whether writing back is warranted:

Worth writing back:

• Synthesized new insights across 3+ articles
• Discovered undocumented connections between articles
• The user's question reveals a knowledge gap worth filling
• Produced a reusable comparison analysis or decision matrix

Not worth writing back:

• Simple lookup ("which article covers X")
• Answer comes entirely from a single article
• One-off question

4a. If worth writing back, use AskUserQuestion to ask:

"This query produced valuable synthesized knowledge: {brief description}. Save as a new note? Suggested title: {title}, directory: {dir}/"

Upon user confirmation:

1. Determine directory per the Directory Mapping Rules in ../../_shared/common-steps.md
2. Search for bidirectional links per Bidirectional Link Search
3. Write the new note with complete frontmatter:
   • title: synthesis note title
   • date: today's date
   • tags: 3-8 relevant tags
   • type: inferred per Type Inference Rules in ../../_shared/common-steps.md
   • confidence: cross-article synthesis is typically medium
   • related: source article list ("[[article-name]]" format)
   • summary: 1-3 sentence synthesis summary
   • source: "Vault Query synthesis"
4. Update index.md: per the Index Update steps in ../../_shared/common-steps.md, append the new article to the corresponding section

Step 5: Report

Output to user:

• Synthesized answer (with [[wikilink]] citations)
• List of referenced articles
• If written back, report the save location
• If knowledge gaps were found, suggest topics to add