references/query-workflow.md
Query Workflow
The flow the LLM follows when the user runs /wiki-query <question> or dispatches the wiki-librarian sub-agent.
Core principle
Read index.md first, then drill in. Do NOT grep the entire wiki on every query — the index is there precisely so you don't have to.
Step-by-step
1. Read index.md
The index is the catalog. Scan it and pick the 3-10 pages most likely to contain the answer. Pick across categories: a good query usually pulls from synthesis/ for the big picture, concepts/ for definitions, sources/ for evidence, and entities/ for context.
2. Read the picked pages
Read them in full. These are short, curated, and already cross-referenced. The wiki has done the hard work for you.
3. Follow wikilinks opportunistically
If a read page points to another page that's clearly relevant, follow it. Don't follow blindly — stop when you have enough.
4. Fall back to search if needed
If the index doesn't surface the right page, use:
python scripts/wiki_search.py --vault . --query "<terms>" --limit 5
BM25 search over wiki pages. Standard library only. Use when:
- The index is stale (flag this to the user — it means lint time)
- The user asks about something niche that doesn't have its own page yet
- You're doing a sweeping search across many pages
5. Synthesize the answer
Compose the answer as:
- A direct answer in 1-3 sentences
- Supporting detail, organized thematically
- Inline citations using wikilinks to source pages:
[[sources/monosemanticity]] - A "Related pages" section at the end with 3-5 wikilinks
6. Offer to re-file
Every good answer is a candidate wiki page. At the end of the answer, ask:
Should I file this as a new page in the wiki? Suggested location:
wiki/comparisons/sae-vs-probing.md— or I can append it to an existing page.
If the user says yes:
- Pick the right category (most often
comparisons/orsynthesis/) - Use the appropriate template
- Add frontmatter with
category,summary,sources(count of cited sources),updated - Update
index.md - Append to
log.mdwithop: createand the question as the title
This is how the wiki compounds — explorations don't disappear into chat history.
Output formats
Not every query wants a markdown answer. Offer the user:
- Markdown page (default) — filed back as a wiki page
- Comparison table — for "A vs B" questions
- Marp slide deck — via
python scripts/export_marp.pyon the synthesis page - Chart (matplotlib) — for data-driven questions; save to
wiki/assets/charts/ - Obsidian Canvas — for visual exploration (JSON format, stored at
wiki/canvases/)
Anti-patterns
- ❌ Read every page in the wiki on every query → use the index
- ❌ Answer without citations → every claim must link to a page
- ❌ Create a new page for a one-off trivial question → only file back answers worth keeping
- ❌ Invent content not in the wiki → if you don't know, say so and suggest a new source to ingest
- ❌ Skip the
log.mdentry when filing an answer back