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:**
```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 /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:

```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 — 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:

```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_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**.

**If `graph_not_available`:**
Skip to step 2.1. No warning — this is the normal path for fresh vaults.

---

### 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 (resolved from graph nodes or grep)
- Graph-only nodes: concepts/entities from `graph.json` with no vault `.md` (label + community + edge metadata only)
- Wikilinks between resolved entities (structural relationships)
- External URLs found in entity content (Confluence, GDocs, GitHub)
- A record of which search terms were covered by the graph vs. which fell back to grep
- 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 Assess graph coverage

Before escalating to a live `/graphify` call, assess whether the cumulative `graph.json`
already covers the gap identified in Phase 3.1. Live `/graphify` invocations are a last resort —
they re-extract what is likely already indexed.

**Step 1 — Check if graph was available in Phase 2.0:**

- If Phase 2.0 determined `graph_not_available`: display the warning below, ask the user whether to build the graph now, and wait for their response before proceeding.
- If Phase 2.0 determined `graph_available`: proceed to Step 2.

> [!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.

After displaying the warning, ask the user:

> "O knowledge graph não está disponível, o que pode tornar esta resposta incompleta. Deseja reconstruí-lo agora antes de continuar?
> Se sim, rode: `/graphify build` — isso indexa todos os atores cadastrados no vault e pode levar alguns minutos.
> Responda **sim** para aguardar e tentar novamente, ou **não** para continuar com o conteúdo disponível."

- **If the user responds "sim" (or equivalent affirmative):**
  1. Inform: "Aguardando `/graphify build`…"
  2. Invoke `/graphify build` via the Skill tool
  3. After completion, re-run the Phase 2.0 availability check
  4. If `graph.json` is now available, continue to Step 2
  5. If still unavailable: inform the user and skip to Phase 4 with vault-only content

- **If the user responds "não" (or equivalent negative), or does not respond:**
  Skip to Phase 4 with vault-only content. Never block indefinitely.

**Step 2 — Assess coverage for the specific gap:**

Using the nodes collected in Phase 2.0, evaluate whether the gap identified in Phase 3.1 is covered:

- If the gap is about relationships or dependencies: check whether `graph.json` nodes for the relevant entities have edges. If yes, read the edges section of `graph.json` filtered to those node IDs and incorporate into the working context. Only invoke live `/graphify` if edges are also insufficient.
- If the gap is about a domain or concept with **zero** graph nodes (Phase 2.0 produced no matches for those search terms): live `/graphify` is warranted — proceed to 3-G.1.
- **When in doubt, escalate.** The coverage assessment is a soft gate — if there is any uncertainty about whether the graph covers the gap, proceed to 3-G.1 and invoke live `/graphify`.

#### 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": [
    {"source": "node_id", "target": "node_id", "relation": "calls|references|...", "confidence": "EXTRACTED|INFERRED|AMBIGUOUS", "confidence_score": 0.9}
  ],
  "communities": {
    "0": {"label": "Community Name", "node_ids": ["id1", "id2"]}
  },
  "traversal": {"mode": "bfs|dfs", "depth": 3, "budget_used": 1200}
}
```

- **If JSON parses successfully:** accumulate nodes, edges, and communities.
- **If parsing fails:** log warning "Graphify call N failed — skipping." Continue with next call.
- **If ALL calls fail:** continue to Phase 4 with vault-only content. Never block.

#### 3-G.3 Deduplicate and blend

1. Deduplicate nodes by `id`, edges by `source+target+relation`
2. Resolve graphify nodes to vault `.md` files (by label or source_file)
3. Merge with the vault entities already collected in Phase 2
4. Respect the 15-entity total limit

#### 3-G.4 Check for remote content need

If graphify results reveal additional external URLs that appear relevant to the question
and aren't ingested in the vault → escalate to Phase 3-T before proceeding.

---

### Phase 3-T — Teach Delegation

Execute when the self-assessment determines `needs_remote_content`, or when Phase 3-G.4
identifies uningested URLs.

#### 3-T.1 Identify URLs to ingest

From the vault entities read in Phase 2 (and optionally Phase 3-G), identify external URLs
that appear directly relevant to answering the question:
- Confluence URLs (containing `confluence` or `atlassian.net`)
- Google Docs URLs (containing `docs.google.com`)
- GitHub URLs (containing `github.com`)

**Limit:** 2 URLs per `/bedrock:ask` invocation. If more than 2 relevant URLs exist,
prioritize those most directly related to the question.

#### 3-T.2 Invoke /bedrock:learn

For each URL, invoke `/bedrock:learn` via the Skill tool:

```
/bedrock:learn <URL>

Context: Ingesting to answer the question: "<original question>"
```

**IMPORTANT:**
- Invoke via the Skill tool — same delegation pattern as teach → preserve
- `/learn` handles its own flow: fetch content, extract entities, present to user for confirmation, delegate to `/preserve`
- `/ask` waits for `/learn` to complete

#### 3-T.3 Re-read newly created entities

After `/learn` completes successfully:
1. Search the vault for entities that were just created or updated (based on `/learn`'s output)
2. Read these new entities (frontmatter + body)
3. Add them to the working set of vault entities for response composition

#### 3-T.4 Best-effort fallback

If `/learn` fails or the user declines the confirmation:
- Log: "Teach delegation for <URL> did not complete. Continuing with available content."
- Continue to Phase 4 with whatever content is available
- **Never block the response** because of a failed teach delegation

---

## Phase 4 — Prioritize by Recency

### 4.1 Identify entities with explicit dates

For discussions and topics, extract the date from the filename:
- Pattern `YYYY-MM-DD-slug.md` → full date (e.g.: `2026-04-02`)
- Pattern `YYYY-MM-slug.md` → partial date, assume day 01 (e.g.: `2026-04-01`)

For consolidated entities (actors, people, teams, projects):
- Treat as equally up-to-date — do not apply temporal ranking
- Trust that content is up-to-date via `/bedrock:preserve` and `/bedrock:compress`

### 4.2 Sort by recency

When the response involves multiple dated discussions or topics:
- Sort by date descending (most recent first)
- If the question is explicitly about something recent ("what happened lately",
  "latest decisions"), limit to entities from the last 30 days
- If the question is about history ("what happened with X over time"),
  include all dates but present chronologically (most recent first)

---

## Phase 5 — Respond to the User

### 5.1 Compose the response

Build the response following these rules:

1. **Language:** Use the vault's configured language. Technical terms in English are accepted (PCI DSS, API, EKS, etc.)

2. **Response structure:**
   - Open with a direct answer to the question (1-3 sentences)
   - If necessary, expand with details organized by topic
   - Use headers (`##`, `###`) if the response is long (>5 paragraphs)
   - Use tables when the information is comparative or inventory-like

3. **Entity citations:**
   - Cite ALL consulted entities as wikilinks: `[[entity-name]]`
   - Use bare wikilinks (never `[[dir/entity-name]]`)
   - Group citations at the end if there are many, or inline when natural

4. **Escalation transparency:**
   - If graphify was used, note: "I consulted the knowledge graph for deeper context."
   - If /learn was invoked, note: "I ingested [source] into the vault to answer this question."
   - If vault-only was sufficient, no special note needed

5. **When nothing is found:**
   - State explicitly: "I didn't find information about [X] in the vault."
   - If relevant, suggest: "You can use `/bedrock:learn <URL>` to ingest a source about this topic."
   - **NEVER fabricate information.** Only respond with what was found.

6. **Response prioritization (Zettelkasten hierarchy):**
   When composing the response, apply weight by Zettelkasten role:
   - **Permanent notes** (actors, people, teams) — maximum weight, consolidated information. Present as current facts.
   - **Bridge notes** (topics, discussions) — high weight, contextualized information. Most recent discussions/topics first.
   - **Index notes** (projects) — medium weight, organizational reference. Point to where the detail is.
   - **Fleeting notes** — low weight, unconsolidated information. **ALWAYS** flag with disclaimer:
     `(source: fleeting note — unconsolidated information)`
   - If there is conflicting information between sources, point out the discrepancy.

7. **Fleeting note promotion detection (criterion 3: active relevance):**
   When a fleeting note is referenced in the response because it is relevant to the query:
   - Check if it meets promotion criteria (see `<base_dir>/../../entities/fleeting.md`):
     - Critical mass (>3 paragraphs with sources)
     - Corroboration (confirmed by an existing permanent)
   - If any criterion is met, add at the end of the response:
     `> [!info] Promotion suggested: [[fleeting-note-name]] can be promoted to permanent/bridge`
   - `/bedrock:ask` does NOT promote automatically — it only flags. Promotion happens when
     `/bedrock:preserve` is invoked with the instruction to promote.

### 5.2 Post-response suggestions

When appropriate, suggest actions to the user:

- If information is outdated: "The vault may be outdated about [X]. Consider running `/bedrock:learn <source>` to update."
- If the question revealed gaps: "I didn't find [Y] in the vault. If you have this information, you can use `/bedrock:preserve` to record it."
- If the question is complex and the response incomplete: "For a more complete view, you may also want to run `/bedrock:learn <URL>` to ingest additional sources."

---

## Critical Rules

| Rule | Detail |
|---|---|
| Vault-first principle | Phase 2 ALWAYS runs before any escalation. Read vault content first, decide later. Never skip Phase 2. |
| LLM self-assessment | The decision to escalate is made by the LLM after reading vault content (Phase 3.1), not by a heuristic rule table. Use the guidance provided, but the LLM makes the final call. |
| Escalation priority | When multiple outcomes apply: `needs_remote_content` > `needs_graphify` > `vault_sufficient`. Internalize first, then analyze. |
| No direct writes | `/ask` NEVER writes, edits, or deletes files directly. All writes are delegated through `/bedrock:learn` → `/bedrock:preserve`. |
| Teach delegation via Skill tool | Invoke `/bedrock:learn` via the Skill tool. `/learn` owns its confirmation gate. `/ask` cannot bypass it. |
| Graphify via Skill tool | Invoke `/graphify` via the Skill tool — NEVER call the Python API directly. |
| Max graphify calls | Read `query.max_graphify_calls` from `.bedrock/config.json` (default: 3, valid range: 1–5). Only consumed when graphify is actually invoked. |
| Graph unavailable warning | When `needs_graphify` but `graphify-out/graph.json` is missing, display `> [!warning]` callout with `/graphify build` instruction. Continue with vault-only content. |
| Best-effort escalation | If graphify fails or teach fails or user declines: continue with available content. NEVER block the response. |
| Limit of 15 entities | Do not read more than 15 entities total across Phase 2 + Phase 3 |
| Limit of 2 teach URLs | Do not invoke `/bedrock:learn` for more than 2 URLs per `/bedrock:ask` invocation |
| No fabrication | Respond ONLY with information found in the vault or obtained through escalation. Never fabricate data. |
| Clarification before guessing | If the question is ambiguous, ask for clarification. Do not assume. |
| Vault language with technical terms in English | Response always in the vault's configured language |
| Bare wikilinks | `[[name]]`, never `[[dir/name]]` |
| Consolidated entities = up-to-date | Actors, people, teams do not need temporal ranking |
| Dated discussions/topics = prioritize recent | Sort by date in filename (YYYY-MM-DD) |
| Sensitive data | NEVER display credentials, tokens, PANs, CVVs found in the vault |
| Fleeting notes with disclaimer | ALWAYS flag information from fleeting notes with `(source: fleeting note — unconsolidated information)` |
| Promotion as side-effect | When a relevant fleeting note meets promotion criteria, flag with callout. Do NOT promote automatically. |
| Weight hierarchy | permanent > bridge > index > fleeting. Use as guideline, not mathematical formula. |
| Vault resolution first | Resolve `VAULT_PATH` before any file operation — never assume CWD is the vault |
| All entity paths use `<VAULT_PATH>/` prefix | `<VAULT_PATH>/actors/`, not `actors/` |
| Graph-first in Phase 2 | Phase 2.0 always runs before glob/grep. grep is a fallback for search terms that produced no matching graph nodes, not the primary strategy. |