| name | brain-query |
| description | Efficient lookup against the brain via markdown keyword scan. Logs gaps so the next ingest pass can fill them. Accepts a scope parameter to target the right brain: forge-dev, cycles, project, or all. |
| library | true |
| phase | brain |
| surface | unattended |
| model | claude-haiku-4-5 |
Brain — Query
Single responsibility
Answer a question against the brain wiki, citing source files. Log
unanswered or low-confidence queries as gaps for brain-ingest to
address.
This skill is invoked first by every other skill, per ADR 010.
Scope routing
| Scope | What to search |
|---|
forge-dev | brain/forge-dev/themes/ + category indexes |
cycles | brain/cycles/themes/ + category indexes |
project | brain/projects/<name>/themes/ + profile.md (forge repo, ADR 035) |
all | union of all three (emit a scope-missing warning) |
Role defaults (the calling skill or orchestrator should supply these):
| Role | Default scope |
|---|
| architect / PM | cycles,project (Brain 2 + the cycle's Brain 3) |
| reflector | all (loose read access; reflector is operator-coupled) |
| dev-loop / reviewer | project (Brain 3 of the cycle's project ONLY) |
| forge-dev session (no cycle) | forge-dev,cycles (Brain 1 + Brain 2) |
Inputs
- A natural-language question or list of questions.
- Optional:
scope — which brain(s) to search (see table above).
- Optional:
project name — required when scope=project.
- Optional: category filter (
pattern | antipattern | decision | operation | reference).
Outputs
{
answers: Array<{
question: string;
answer: string;
confidence: 'high' | 'medium' | 'low';
sources: string[];
gap?: boolean;
}>;
}
For each gap: true answer, append to _logs/<cycle-id>/brain-gaps.jsonl.
Event-log entries to emit
brain-query.start — with the questions.brain-query.hit — one event per question that found high/medium-confidence sources.brain-query.gap — one event per question with low/no confidence.brain-query.end — summary.
Process
Keyword scan (all scopes)
- Read the relevant category index for the scope:
- Brain 1 (forge-dev):
brain/forge-dev/decisions.md or brain/forge-dev/reference.md
- Brain 2 (cycles):
brain/cycles/patterns.md, antipatterns.md, operations.md, or decisions.md
- Brain 3 (project):
brain/profile.md + brain/themes/ listing
- Read 2–5 theme files whose slugs or one-liners match the question keywords.
- Synthesise + cite. Write a one-paragraph answer preserving exact terminology from the cited themes. Cite by file path. Score confidence:
- High: ≥ 2 corroborating themes, all on-topic.
- Medium: 1 source on-topic.
- Low / gap: no good source — set
gap: true.
- If still nothing after reading the category index + 2–3 theme candidates, mark
gap: true.
Constraints
- Cite, don't paraphrase deeply. Synthesis is a one-paragraph answer + source list. The caller can read the linked file.
- Cite theme pages only. Valid
sources entries are brain/cycles/themes/<slug>.md, brain/forge-dev/{log.md,decisions.md,reference.md}, and brain/projects/<name>/{profile.md,themes/<slug>.md}. Never cite brain/cycles/_raw/* (inputs to synthesis, not citations) or category indexes (navigation, not knowledge).
- Exhaustive on theme coverage. Recall matters — under-citing (missing the corrective antipattern) is worse than over-citing by 1–2 extras.
- Scope is load-bearing. When
scope: project, cited sources MUST come from inside the project's own brain. Do not pull in forge-dev concepts not documented in the project brain — that's hallucination.
- Missing scope defaults to
all + warn. Emit: [brain-query] no scope supplied — searching all three brains; supply --scope to reduce noise.
- Gaps are logged, not silently failed. If the brain doesn't know, the brain learns by the next ingest pass. Naming-the-absence without
gap: true is the worst failure mode.
- No web fallback in this skill. Broader research is the calling skill's responsibility.
- Fast model by default. Haiku is the default; per-skill override via the calling skill's frontmatter.
