/bedrock:ask — Adaptive Vault Reader

Plugin Paths

Entity definitions and templates are in the plugin directory, not at the vault root. Use the "Base directory for this skill" provided at invocation to resolve the paths:

• Entity definitions: <base_dir>/../../entities/
• Templates: <base_dir>/../../templates/{type}/_template.md
• Plugin CLAUDE.md: <base_dir>/../../CLAUDE.md (already automatically injected into context)

Where <base_dir> is the path provided in "Base directory for this skill".

Vault Resolution

Resolve which vault to query. This skill can be invoked from any directory.

Step 1 — Parse --vault flag: Check if the input arguments include --vault <name>. If found, extract the vault name and remove it from the arguments (the remaining text is the question).

Step 2 — Resolve vault path:

1. If --vault <name> was provided: Read the vault registry at <base_dir>/../../vaults.json. Find the entry matching the name. If not found: error — "Vault <name> is not registered. Run /bedrock:vaults to see available vaults." If found: set VAULT_PATH to the entry's path value.

2. If no --vault flag — CWD detection: Read <base_dir>/../../vaults.json. Check if the current working directory is inside any registered vault path (CWD starts with a registered vault's absolute path). If multiple match, use the longest path (most specific). If found: set VAULT_PATH to the matching vault's path.

3. If CWD detection fails — default vault: From the registry, find the vault with "default": true. If found: set VAULT_PATH to the default vault's path.

4. If no resolution: Error — "No vault resolved. Available vaults:" followed by the registry listing. "Use --vault <name> to specify, or run /bedrock:setup to register a vault."

Step 3 — Validate vault path:

test -d "<VAULT_PATH>" && echo "exists" || echo "missing"

If missing: error — "Vault path <VAULT_PATH> does not exist on disk. Run /bedrock:setup to re-register."

Step 4 — Read vault config:

cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null

Extract language and other relevant fields for use in later phases.

From this point forward, ALL vault file operations use <VAULT_PATH> as the root.

• Entity directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, etc.
• Graphify output: <VAULT_PATH>/graphify-out/

Overview

This skill receives a natural language question and answers it using an adaptive, vault-first approach. It always reads vault content first, then decides whether to escalate to graphify or /learn ased on what's actually needed — not what the question looks like in isolation.

You are an adaptive context orchestrator agent. You only READ — never write, edit, or delete files directly.

Writes happen exclusively through /bedrock:learn delegation (which flows through /bedrock:preserve). If the query reveals outdated or missing information and no remote source is available to ingest, suggest that the user run /bedrock:preserve or /bedrock:learn to update the vault.

Phase 0 — Read Configuration

0.1 Load config

Read .bedrock/config.json from the vault root:

if [ -f ".bedrock/config.json" ]; then
    cat .bedrock/config.json
else
    echo "config_not_found"
fi

• If config exists: extract the value of query.max_graphify_calls. Store as max_graphify_calls.
• If config does not exist or field is absent: set max_graphify_calls = 3 (default).
• Valid range: 1–5. If the value is outside this range, clamp to the nearest bound and log a warning.

Phase 1 — Analyze the Question

1.1 Classify the question

Read the user's question and identify:

1. Mentioned entities — names of systems, people, teams, topics, projects, or discussions. They may appear as:

   • Exact filename (e.g.: "billing-api", "squad-payments")
   • Human-readable name (e.g.: "Billing API", "Squad Payments")
   • Alias or acronym (e.g.: "BillingAPI", "BRB")
   • Contextual reference (e.g.: "the billing service", "the notifications team")

2. Relevant domain(s) — payments, notifications, orders, integrations, checkout, compliance, internal-tools. Infer from the mentioned entities or the question context.

3. Type of information sought:

   • Status/overview — "what is X?", "what's the status of X?"
   • Architecture/stack — "how does X work?", "what's the stack of X?"
   • People/teams — "who owns X?", "who works with Y?"
   • History/decisions — "what was decided about X?", "what happened with Y?"
   • Relationships — "what depends on X?", "how does Y relate to Z?"
   • Deprecation — "what is being deprecated?", "what's the deprecation plan for X?"

1.2 Assess clarity

If the question is too ambiguous to produce a targeted search (e.g.: "tell me everything", "how does the system work?", "what's going on?"), ask for clarification:

"Your question is broad. Can you specify: which system, team, or topic would you like to know more about?"

If the question mentions something that clearly isn't part of the vault (e.g.: something personal, unrelated technology), inform: "I didn't find anything in the vault about this."

1.3 Phase 1 classification result

At the end, you should have:

• search_terms: list of names, aliases, and keywords to search for
• domains: list of relevant domains (may be empty if not identified)
• info_type: classification of the type of information sought
• explicit_entities: entities mentioned directly by name (if any)

Phase 2 — Graph-First Search

This phase always runs for every question. It uses the cumulative knowledge graph as the primary index when available, falling back to glob/grep for terms not represented in the graph. Never skip this phase.

2.0 Check graph.json and score nodes

Before any glob/grep, check if the cumulative knowledge graph is available:

if [ -f "<VAULT_PATH>/graphify-out/graph.json" ] && [ -s "<VAULT_PATH>/graphify-out/graph.json" ]; then
    echo "graph_available"
else
    echo "graph_not_available"
fi

If graph_available:

1. Read <VAULT_PATH>/graphify-out/graph.json — extract only the nodes array (skip edges to avoid context explosion on large graphs). If the nodes array exceeds 500 entries, read only the first 500 — graphify orders nodes by centrality, so high-value nodes come first.

2. From the nodes array, extract per node: id, label, file_type, source_file, community, is_god_node.

3. Score nodes by relevance to the search terms from Phase 1:

   • Primary signal: node label contains or closely matches any search term
   • Secondary signal: node belongs to a community that contains other high-scoring nodes (community resonance)
   • Boost: is_god_node: true nodes get elevated priority when their label is even loosely relevant to the query

4. Select top N nodes (N ≤ 15, same limit as the current entity read budget). Track which search terms produced ≥ 1 matching node and which produced none.

5. For each selected node with a non-null source_file:

   • Resolve the corresponding vault .md file: search for the source_file basename in entity directories

     Glob: <VAULT_PATH>/actors/<basename>.md, <VAULT_PATH>/people/<basename>.md, <VAULT_PATH>/teams/<basename>.md,
           <VAULT_PATH>/topics/*<basename>*.md, <VAULT_PATH>/discussions/*<basename>*.md, <VAULT_PATH>/projects/<basename>.md
     

   • If found: read the full entity file — this node is fully resolved (skip steps 2.2–2.4 for this entity)
   • If not found: record graph metadata only (label, community, relevant edge labels) — use this metadata in Phase 5 response to surface the concept even without a vault file

6. For each search term that produced zero matching graph nodes → proceed to steps 2.2–2.4 (glob/grep) for that term only.