/ask

name: ask
description: >
  Adaptive vault reader skill. Receives a natural language question,
  uses graph.json as the primary index (Phase 2.0) before any glob/grep,
  then self-assesses whether more context is needed. Escalates to live /graphify
  only when graph coverage is insufficient, or to /bedrock:learn for remote content
  ingestion. Answers simple questions with zero graphify calls.
  Use when: "bedrock ask", "bedrock-ask", "/bedrock:ask", any question about the vault,
  "what do we know about", "who owns", "what's the status of", "tell me about",
  "how does it work", or any Second Brain query.
user_invocable: true
allowed-tools: Bash, Read, Glob, Grep, Skill, Agent

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