wicked-brain-query

name: wicked-brain:query description: | Answer questions by searching and synthesizing brain content. Dispatches a query subagent that searches, reads, follows links, and produces a cited answer.

Use instead of Agent(Explore) or reading files directly for any conceptual question: "what does X do", "how does Y work", "explain Z", "tell me about W", "why does X happen", "give me context on Y", or any question that could be answered from indexed knowledge. Always try this before exploring the codebase manually.

wicked-brain:query

Answer questions from the brain's content by dispatching a query subagent. The default path is a direct search → read → synthesize. Reserve the heavier steps (synonym expansion, grep, backlinks) for when the direct search is thin.

Config

Brain discovery + server lifecycle are handled by wicked-brain-call. Pass --brain <path> to override the auto-detected brain, or set WICKED_BRAIN_PATH. The CLI starts the server on first call (no manual init) and writes an audit record to {brain}/calls/ per call.

Parameters

• question (required): the question to answer

Process

Dispatch a query subagent with these instructions:

You are a research agent for the digital brain at {brain_path}.
Server interactions: use `npx wicked-brain-call <action> [--param k=v ...]`.

Question: "{question}"

## Step 1: Search (default path)

Extract 2-4 key terms from the question (noun phrases, named entities,
technical terms — not full sentences or common words). Search the brain:

```bash
npx wicked-brain-call search --param query={term} --param limit=10 --param session_id={session_id}

Pass a consistent session_id for the whole conversation (any stable string — a timestamp or UUID). It drives access tracking and diversity ranking.

The envelope carries brain_id — note WHICH brain answered; cite it in the final answer. If the question implies recency ("recently", "this week", "latest"), add --param since={iso8601_date} (e.g. the date 7 days ago).

If the searches return enough to answer the question, go straight to Step 2.

Fallback: expand only when results are thin (0-2 hits)

Only if the direct searches came back sparse:

• Read {brain_path}/_meta/synonyms.json if it exists (skip on fresh brains — it's auto-generated by wicked-brain:retag). For each key term that matches a synonym key, re-search with the learned synonyms. Learned synonyms beat guesses — they come from real usage.
• For terms not in the map, add 1-2 LLM-generated synonyms ("auth" → "authentication", "credentials"; "DB" → "database") and re-search.
• Still thin? Grep for exact phrases (prefer your Grep tool — cross-platform): macOS/Linux: grep -rl "{terms}" {brain_path}/chunks/ {brain_path}/wiki/ | head -10 Windows: Get-ChildItem -Recurse -Path "{brain_path}\chunks","{brain_path}\wiki" -Filter *.md | Select-String -Pattern "{terms}" -List | Select-Object -First 10 -ExpandProperty Path

Dedupe results before reading.

Step 2: Progressive read

Read the top 3-5 results at depth 1 (frontmatter + summary), then the most promising 1-3 at depth 2 (full content). Use the Read tool; parse frontmatter between --- lines.

Step 3: Follow links (only if context is incomplete)

If the answer still has gaps, follow [[wikilinks]] in the content you read (local [[path]] → read it; cross-brain [[brain::path]] → read if accessible), and check backlinks for what else references a key result:

npx wicked-brain-call backlinks --param id={result_path}

Step 4: Synthesize answer

• Cite sources: [source: {path}] for every factual claim.
• If evidence is insufficient, say so explicitly.
• If sources conflict, note the contradiction.
• Keep it concise — the user asked a question, not for a report.

Report format

Lead with which brain answered, then the answer and sources:

"(brain: {brain_id}) {Answer text with [source: path] citations}"

Sources:

• {path}: {one-line description of what it contributed}

Step 5: Emit bus event (fire-and-forget)

npx wicked-bus emit \
  --type "wicked.query.executed" \
  --domain "wicked-brain" \
  --subdomain "brain.query" \
  --payload '{"question":"{question}","sources_found":{count},"brain_id":"{brain_id}"}' 2>/dev/null || true

If the bus is not installed, silently skip.

Step 6: Log a search miss (only if evidence was insufficient)

Append to {brain_path}/_meta/log.jsonl: {"ts":"{ISO}","op":"search_miss","query":"{original question}","key_terms":[{terms}],"results_found":{count},"author":"agent:query"}