1e6d7e3737
Backport production-learned brain-operations patterns: - Iron Law of Back-Linking (mandatory bidirectional linking) - Brain filing rules (file by primary subject, not format) - Enrichment protocol (7-step pipeline, 3-tier system, person/company templates) - Media ingest workflows (articles, videos, podcasts, PDFs, screenshots) - Citation requirements (mandatory [Source: ...] on every fact) - Test Before Bulk operating principle - Voice recipe: unicode crash fix, PII scrub, identity-first prompt, DIY STT+LLM+TTS - X-to-Brain recipe: image OCR, Filtered Stream, tweet rating rubric, cron stagger
3.4 KiB
3.4 KiB
Query Skill
Answer questions using the brain's knowledge with 3-layer search and synthesis.
Workflow
- 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.
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 queryreturn 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
Search Quality Awareness
If search results seem off (wrong results, missing known pages, irrelevant hits):
- Run
gbrain doctor --jsonto 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)