ask

# /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:** ```bash 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:** ```bash 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 /teach based 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:teach` 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:teach` to update the vault. --- ## Phase 0 — Read Configuration ### 0.1 Load config Read `.bedrock/config.json` from the vault root: ```bash 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 — Vault-First Search This phase **always runs** for every question, regardless of graph availability. It is the foundation of the adaptive approach — read vault content first, decide later. ### 2.1 Read entity definitions Use Read to read the entity definition files from the plugin (see "Plugin Paths" section): - If the question is about a system → read `<base_dir>/../../entities/actor.md` - If the question is about a person → read `<base_dir>/../../entities/person.md` - If the question is about a team → read `<base_dir>/../../entities/team.md` - If the question is about a topic/deprecation → read `<base_dir>/../../entities/topic.md` - If the question is about a meeting/decision → read `<base_dir>/../../entities/discussion.md` - If the question is about a project/initiative → read `<base_dir>/../../entities/project.md` - If you don't know the type → read all entity definitions from the plugin to classify correctly ### 2.2 Search entities by name and alias For each search term identified in Phase 1: **Step 1 — Search by filename:** ``` Glob: <VAULT_PATH>/actors/<term>*.md, <VAULT_PATH>/people/<term>*.md, <VAULT_PATH>/teams/<term>*.md, <VAULT_PATH>/topics/*<term>*.md, <VAULT_PATH>/discussions/*<term>*.md, <VAULT_PATH>/projects/<term>*.md, <VAULT_PATH>/fleeting/*<term>*.md ``` **Step 2 — Search by alias in frontmatter:** ``` Grep: pattern="aliases:.*<term>" in directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, <VAULT_PATH>/teams/, <VAULT_PATH>/topics/, <VAULT_PATH>/discussions/, <VAULT_PATH>/projects/ (case-insensitive) ``` **Step 3 — Search by name in frontmatter:** ``` Grep: pattern="name:.*<term>" or pattern="title:.*<term>" in the same directories (case-insensitive) ``` **Step 4 — Search by content (fallback):** If steps 1-3 did not return sufficient results: ``` Grep: pattern="<term>" in entity directories (case-insensitive) ``` ### 2.3 Filter by domain If domains were identified in Phase 1, filter results: ``` Grep: pattern="domain/<domain>" in the found files (tags field of frontmatter) ``` Keep all results, but prioritize those matching the domain. ### 2.4 Read found entities For each entity found (limit: 15 entities): 1. Read the frontmatter first (~first 30 lines) to confirm relevance 2. If relevant: read the full file 3. If not relevant (false positive from Grep): discard Record for each entity read: - filename, type, name - wikilinks found in frontmatter and body - external URLs found in the content (Confluence, Google Docs, GitHub) - Explicit date in the filename (if any) ### 2.5 Follow wikilinks (1 level of depth) For each extracted wikilink that is relevant to the question: 1. Resolve the file: search for `<wikilink-name>.md` in entity directories ``` Glob: <VAULT_PATH>/actors/<name>.md, <VAULT_PATH>/people/<name>.md, <VAULT_PATH>/teams/<name>.md, <VAULT_PATH>/topics/*<name>*.md, <VAULT_PATH>/discussions/*<name>*.md, <VAULT_PATH>/projects/<name>.md ``` 2. Read the found file (frontmatter + body) 3. **Do NOT follow wikilinks from this second level** — stop here to avoid context explosion **Relevance criteria for following a wikilink:** - The question is about relationships ("who owns", "what depends on") → follow all - The question is about status/overview → follow team, people (focal points) - The question is about history → follow related discussions, topics - The question is about architecture → follow dependent actors **Limit:** Do not read more than 15 entities total (2.4 + 2.5 combined). If the limit is reached, prioritize entities directly mentioned in the question. ### 2.6 Phase 2 output At the end of Phase 2, you have: - A set of vault entities with their full content - Wikilinks between them (structural relationships) - External URLs found in their content (Confluence, GDocs, GitHub) - A sense of whether the vault content covers the question --- ## Phase 3 — Context Assessment + Conditional Escalation This is the core decision point. After reading vault content in Phase 2, assess whether you have enough context to answer the question. ### 3.1 Self-Assessment Evaluate the vault content you read in Phase 2 against the original question. Determine one of three outcomes: **`vault_sufficient`** — You have enough information to compose a good answer. Indicators: - The question is factual/status/ownership and the vault entities contain a clear answer - Examples: "who owns X", "what's the status of Y", "what team manages Z", "what is X" - The entities read in Phase 2 directly address the question - No significant gaps in the information **`needs_graphify`** — The vault content is partial but the knowledge graph could fill the gaps. Indicators: - The question involves code-level relationships, cross-domain dependencies, or architectural paths - The vault entities reference systems whose connections aren't explicit in the markdown - You feel you're missing structural context that the knowledge graph could provide - Examples: "how does X connect to Y at the code level", "what are the dependencies of X", "trace the data flow from A to B" **`needs_remote_content`** — The vault entities reference external URLs that appear directly relevant to the question, but the content behind those URLs isn't ingested in the vault. Indicators: - An entity's `sources` field or body text contains a URL (Confluence, GDocs, GitHub) that likely holds the answer - The question asks about something documented externally (e.g., "what's the runbook for X" and the entity links to a Confluence page) - The vault has a pointer to the answer but not the answer itself **Priority when multiple outcomes apply:** `needs_remote_content` > `needs_graphify` > `vault_sufficient` Rationale: remote content must be internalized first for the vault to be complete. Graphify can run on richer data after ingestion. If both apply, handle remote content first, then re-assess whether graphify is still needed. **After determining the outcome:** - `vault_sufficient` → skip directly to **Phase 4** (recency) then **Phase 5** (respond) - `needs_graphify` → proceed to **Phase 3-G** - `needs_remote_content` → proceed to **Phase 3-T** --- ### Phase 3-G — Graphify Escalation Execute only when the self-assessment determines `needs_graphify`. #### 3-G.0 Check graph availability ```bash 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_not_available`:** Display the following warning and skip to Phase 4 with vault-only content: > [!warning] Knowledge graph unavailable > The knowledge graph is not available (`<VAULT_PATH>/graphify-out/graph.json` missing or empty). > The answer below is based on vault content only — it may be incomplete for this type of question. > Run `/graphify build` to rebuild the graph from the vault's actor repositories. #### 3-G.1 Formulate graphify calls Based on the gap between what you have (Phase 2 content) and what the question needs, formulate 1–N graphify calls. Use the same modes as before: | Gap identified | Graphify mode | |---|---| | Need to understand a single entity's code structure | `explain "<entity>"` | | Need to find how two entities connect | `path "<entityA>" "<entityB>"` | | Need broad relationship or dependency context | `query "<question about the gap>"` | The LLM decides the calls based on what's missing — not from a pre-planned decomposition. Never exceed `max_graphify_calls`. #### 3-G.2 Execute graphify calls sequentially For each call, invoke `/graphify` via the Skill tool. Append the structured JSON output instruction: ``` After completing the traversal, return ONLY a JSON object with this structure (no prose, no markdown fences): { "mode": "query|path|explain", "start_nodes": ["node_id1", "node_id2"], "nodes": [ {"id": "node_id", "label": "Human Readable Name", "source_file": "relative/path", "community": 0, "source_location": "file:line"} ], "edges": [