Query Skill
Answer questions using the brain's knowledge with 3-layer search and synthesis.
Contract
This skill guarantees:
- Every answer is grounded in brain content (no hallucination)
- Every claim has a citation tracing back to a specific page slug
- Gaps are flagged explicitly ("the brain doesn't have information on X")
- Source precedence is respected (user statements > compiled truth > timeline > external)
- Conflicting sources are noted with both citations
Phases
- Decompose the question into search strategies:
- Keyword search for specific names, dates, terms
- Semantic query for conceptual questions
- Structured queries (list by type, backlinks) for relational questions
- Execute searches:
- Keyword search gbrain for FTS matches (search)
- Hybrid search gbrain for semantic+keyword with expansion (query)
- List pages in gbrain by type or check backlinks for structural queries
- Read top results. Read the top 3-5 pages from gbrain to get full context.
- Synthesize answer with citations. Every claim traces back to a specific page slug.
- Flag gaps. If the brain doesn't have info, say "the brain doesn't have information on X" rather than hallucinating.
Anti-Patterns
- Answering from general knowledge when the brain has relevant content
- Hallucinating facts not in the brain
- Silently picking one source when sources conflict
- Loading full pages when search chunks are sufficient
- Ignoring source precedence (user statements are highest authority)
Output Format
Answers should include:
- Direct response to the question
- Citations: "According to [Source: people/jane-doe, compiled truth]..."
- Gap flags: "The brain doesn't have information on X"
- Conflict notes when sources disagree
Quality Rules
- Never hallucinate. Only answer from brain content.
- Cite sources: "According to concepts/do-things-that-dont-scale..."
- Flag stale results: if a search result shows [STALE], note that the info may be outdated
- For "who" questions, use backlinks and typed links to find connections
- For "what happened" questions, use timeline entries
- For "what do we know" questions, read compiled_truth directly
Token-Budget Awareness
Search returns chunks, not full pages. Read the excerpts first before deciding
whether to load a full page.
gbrain search / gbrain query return ranked chunks with context snippets.
These are often enough to answer the question directly.
- Only use
gbrain get <slug> to load the full page when a chunk confirms the
page is relevant and you need more context (e.g., compiled truth, timeline).
- "Tell me about X" -- get the full page (the user wants the complete picture).
- "Did anyone mention Y?" -- search results are enough (the user wants a yes/no with evidence).
Source precedence
When multiple sources provide conflicting information, follow this precedence:
- User's direct statements (highest authority -- what the user told you directly)
- Compiled truth (the brain's synthesized, cited understanding)
- Timeline entries (raw evidence, reverse-chronological)
- External sources (web search, API enrichment -- lowest authority)
When sources conflict, note the contradiction with both citations. Don't silently
pick one.
Citation in Answers
When referencing brain pages in your answer, propagate inline citations:
- Cite the page: "According to [Source: people/jane-doe, compiled truth]..."
- When brain pages have inline
[Source: ...] citations, propagate them so
the user can trace facts to their origin
- When you synthesize across multiple pages, cite all sources
Graph Traversal (v0.10.1+)
For relationship questions ("who knows who at X?", "connections between A and B",
"who works at Acme?", "who attended the standup?"), use the graph layer instead
of full-text search:
gbrain graph-query <slug> --type <link_type> --depth N --direction in|out|both
- Available link types:
attended, works_at, invested_in, founded, advises, mentions, source
--direction in answers "who points to X?" (e.g., who works at company X)
--direction out answers "what does X point to?" (default)
--depth N controls multi-hop traversal (default 5)
Examples:
- "Who works at Acme?" →
gbrain graph-query companies/acme --type works_at --direction in
- "Who attended Demo Day W26?" →
gbrain graph-query meetings/demo-day-w26 --type attended --direction out
- "What companies has Emily advised?" →
gbrain graph-query people/emily --type advises --direction out
- "Who has Alice met (via meetings)?" →
gbrain graph-query people/alice --type attended --depth 2
Combine with gbrain query for queries that need BOTH semantic similarity AND
graph structure. Search results are ranked with a small backlink boost so well-
connected entities surface higher.
Search Quality Awareness
If search results seem off (wrong results, missing known pages, irrelevant hits):
- Run
gbrain doctor --json to check index health
- Check embedding coverage -- partial embeddings degrade hybrid search
- Compare keyword search (
gbrain search) vs hybrid search (gbrain query)
for the same query to isolate whether the issue is embedding-related
- Report search quality issues in the maintain workflow (see maintain skill)
Tools Used
- Keyword search gbrain (search)
- Hybrid search gbrain (query)
- Read a page from gbrain (get_page)
- List pages in gbrain with filters (list_pages)
- Check backlinks in gbrain (get_backlinks)
- Traverse the link graph in gbrain (traverse_graph)
- View timeline entries in gbrain (get_timeline)
Source: garrytan/gbrain → skills/query/SKILL.md
1---
2name: query
3description: "| Answer questions using the brain's knowledge with 3-layer search, synthesis, and citation propagation. Use when the user asks a question, wants a lookup, or needs information from the brain."
4allowed-tools: "search query get_page list_pages get_backlinks traverse_graph get_timeline"
5category: research-and-academic
6source_repo: garrytan/gbrain
7source_path: "skills/query/SKILL.md"
8source_url: https://github.com/garrytan/gbrain/blob/HEAD/skills/query/SKILL.md
9metadata:
10 source: https://skillmd.com/skills/garrytan/query
11---
12
13
14# Query Skill
15
16Answer questions using the brain's knowledge with 3-layer search and synthesis.
17
18## Contract
19
20This skill guarantees:
21- Every answer is grounded in brain content (no hallucination)
22- Every claim has a citation tracing back to a specific page slug
23- Gaps are flagged explicitly ("the brain doesn't have information on X")
24- Source precedence is respected (user statements > compiled truth > timeline > external)
25- Conflicting sources are noted with both citations
26
27## Phases
28
291. **Decompose the question** into search strategies:
30 - Keyword search for specific names, dates, terms
31 - Semantic query for conceptual questions
32 - Structured queries (list by type, backlinks) for relational questions
332. **Execute searches:**
34 - Keyword search gbrain for FTS matches (search)
35 - Hybrid search gbrain for semantic+keyword with expansion (query)
36 - List pages in gbrain by type or check backlinks for structural queries
373. **Read top results.** Read the top 3-5 pages from gbrain to get full context.
384. **Synthesize answer** with citations. Every claim traces back to a specific page slug.
395. **Flag gaps.** If the brain doesn't have info, say "the brain doesn't have information on X" rather than hallucinating.
40
41## Anti-Patterns
42
43- Answering from general knowledge when the brain has relevant content
44- Hallucinating facts not in the brain
45- Silently picking one source when sources conflict
46- Loading full pages when search chunks are sufficient
47- Ignoring source precedence (user statements are highest authority)
48
49## Output Format
50
51Answers should include:
52- Direct response to the question
53- Citations: "According to [Source: people/jane-doe, compiled truth]..."
54- Gap flags: "The brain doesn't have information on X"
55- Conflict notes when sources disagree
56
57## Quality Rules
58
59- Never hallucinate. Only answer from brain content.
60- Cite sources: "According to concepts/do-things-that-dont-scale..."
61- Flag stale results: if a search result shows [STALE], note that the info may be outdated
62- For "who" questions, use backlinks and typed links to find connections
63- For "what happened" questions, use timeline entries
64- For "what do we know" questions, read compiled_truth directly
65
66## Token-Budget Awareness
67
68Search returns **chunks**, not full pages. Read the excerpts first before deciding
69whether to load a full page.
70
71- `gbrain search` / `gbrain query` return ranked chunks with context snippets.
72 These are often enough to answer the question directly.
73- Only use `gbrain get <slug>` to load the full page when a chunk confirms the
74 page is relevant and you need more context (e.g., compiled truth, timeline).
75- **"Tell me about X"** -- get the full page (the user wants the complete picture).
76- **"Did anyone mention Y?"** -- search results are enough (the user wants a yes/no with evidence).
77
78### Source precedence
79
80When multiple sources provide conflicting information, follow this precedence:
81
821. **User's direct statements** (highest authority -- what the user told you directly)
832. **Compiled truth** (the brain's synthesized, cited understanding)
843. **Timeline entries** (raw evidence, reverse-chronological)
854. **External sources** (web search, API enrichment -- lowest authority)
86
87When sources conflict, note the contradiction with both citations. Don't silently
88pick one.
89
90## Citation in Answers
91
92When referencing brain pages in your answer, propagate inline citations:
93- Cite the page: "According to [Source: people/jane-doe, compiled truth]..."
94- When brain pages have inline `[Source: ...]` citations, propagate them so
95 the user can trace facts to their origin
96- When you synthesize across multiple pages, cite all sources
97
98## Graph Traversal (v0.10.1+)
99
100For relationship questions ("who knows who at X?", "connections between A and B",
101"who works at Acme?", "who attended the standup?"), use the graph layer instead
102of full-text search:
103
104- `gbrain graph-query <slug> --type <link_type> --depth N --direction in|out|both`
105- Available link types: `attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, `source`
106- `--direction in` answers "who points to X?" (e.g., who works at company X)
107- `--direction out` answers "what does X point to?" (default)
108- `--depth N` controls multi-hop traversal (default 5)
109
110Examples:
111- "Who works at Acme?" → `gbrain graph-query companies/acme --type works_at --direction in`
112- "Who attended Demo Day W26?" → `gbrain graph-query meetings/demo-day-w26 --type attended --direction out`
113- "What companies has Emily advised?" → `gbrain graph-query people/emily --type advises --direction out`
114- "Who has Alice met (via meetings)?" → `gbrain graph-query people/alice --type attended --depth 2`
115
116Combine with `gbrain query` for queries that need BOTH semantic similarity AND
117graph structure. Search results are ranked with a small backlink boost so well-
118connected entities surface higher.
119
120## Search Quality Awareness
121
122If search results seem off (wrong results, missing known pages, irrelevant hits):
123- Run `gbrain doctor --json` to check index health
124- Check embedding coverage -- partial embeddings degrade hybrid search
125- Compare keyword search (`gbrain search`) vs hybrid search (`gbrain query`)
126 for the same query to isolate whether the issue is embedding-related
127- Report search quality issues in the maintain workflow (see maintain skill)
128
129## Tools Used
130
131- Keyword search gbrain (search)
132- Hybrid search gbrain (query)
133- Read a page from gbrain (get_page)
134- List pages in gbrain with filters (list_pages)
135- Check backlinks in gbrain (get_backlinks)
136- Traverse the link graph in gbrain (traverse_graph)
137- View timeline entries in gbrain (get_timeline)
138
139---
140
141**Source:** [`garrytan/gbrain`](https://github.com/garrytan/gbrain) → `skills/query/SKILL.md`