query

Query workflow

The user asks a question. Use $ARGUMENTS as the question if provided (e.g., /query How do the main concepts in the wiki relate to each other?).

Prerequisites

• Verify wiki/index.md exists. If missing, suggest running /ingest on a source first — it will bootstrap the wiki automatically.

1. Detect mode. Determine whether the user wants navigation or understanding:

   • Navigational — the input is keywords, a lookup, or asks "where is X?" / "which pages mention X?" / "find X". The user wants a results list, not a composed answer.
   • Synthesis — the input is a natural language question, asks for explanation, comparison, or summary. The user wants an answer.

   Mode override: If the user explicitly says "just search" or "just list pages", use navigational mode regardless of input structure. If the user says "explain" or "synthesize", use synthesis mode. When in doubt, default to synthesis — it's strictly more useful than a list of links.

2. Find relevant pages.

   • Read wiki/index.md to identify candidate pages.
   • Lens filtering (optional): If the user's question specifies a domain or explicitly requests results from a particular lens (e.g., "in the ML lens" or "within compliance"), filter candidates to pages with the matching lens frontmatter field. If no lens is specified, search across all pages (default).
   • If the index is insufficient, use a tiered search:
     • Tier 1 — Filenames: Scan filenames in wiki/ for query term matches.
     • Tier 2 — Headings and frontmatter: Grep for the query in page titles, headings (#), and frontmatter tags/title fields.
     • Tier 3 — Body text: Grep the full body text of remaining pages.
     • For wikis with >50 pages, stop after Tier 2 if 5+ matches are found.

3. Respond according to mode.

   If navigational: Present a concise results list. For each matching page, show:

   • Page title as a [[wikilink]]
   • Page type and tags
   • Most relevant excerpt (1-3 lines of context)
   • If no results: suggest related terms, alternative spellings, or rephrasing as a synthesis question.
   • Do not read full pages or synthesize — keep it cheap and fast.

   If synthesis: Read the relevant wiki pages. For multi-hop questions, follow cross-references across pages. Then synthesize an answer with citations to wiki pages using [[wikilinks]]. Reference raw sources where appropriate with (Source: filename.md).

   • Cross-lens attribution: When synthesizing from pages across multiple lenses, note which lens each source page belongs to so the user understands which domain each claim comes from.
   • Coverage asymmetry check: If the wiki covers one aspect of the question deeply but another shallowly (or not at all), flag this to the user rather than silently filling gaps from general knowledge. State what the wiki covers well, what it lacks, and suggest sources or /ingest actions that could fill the gap.

4. Offer to file the answer. If the answer is valuable enough to compound in the wiki, use the AskUserQuestion tool to offer filing. Value signals: synthesizes multiple pages, reveals a novel connection between concepts, answers a question the wiki should "know" for future queries, or the user explicitly asks to file it. Length alone isn't the criterion — a concise comparison or insight can be worth filing. Before asking, check if a similar page already exists (by searching wiki/index.md). If a similar page exists, options: "Update existing page (Recommended)", "Create new cross-referenced page", "Skip". If no similar page, options: "File as wiki page (Recommended)", "Skip". If the user agrees (or asks directly):

   • Choose the appropriate type: query-answer (factual), comparison, or synthesis
   • Create the page in wiki/synthesis/ following quality standards for that type (see CLAUDE.md)
   • Include proper frontmatter with sources listing all wiki pages that informed the answer
   • Lens assignment for filed pages: If source pages all share the same lens, the filed page gets that lens. If sources span multiple lenses (cross-lens synthesis), omit the lens field — the page belongs to the wiki broadly.
   • Add a ## See also section linking to source pages used
   • Update wiki/index.md (file under Synthesis & Comparisons)
   • Append to wiki/log.md: ## [YYYY-MM-DD] query | Question summary

Answer formats

Adapt the format to the question:

• Navigational/search — results list with wikilinks, types, and excerpts (no synthesis, no full page reads)
• Factual questions — concise answer with citations
• Comparisons — table or structured comparison
• Analysis/synthesis — longer-form markdown with sections
• Lists — bulleted with brief explanations
• Bullet summary — when the user wants a quick overview
• Marp slides — when the user asks to "present", "make slides", or "create a presentation" from wiki content. Produce a Marp-format markdown file (with marp: true frontmatter, --- slide separators). Save outside wiki/ at a user-specified or sensible default location.
• Mermaid diagrams — when the user asks to "diagram", "visualize", "map", or "show how X relates to Y". Produce a mermaid code block (flowchart, mindmap, timeline, or entity-relationship as appropriate). Can be inline in the answer or saved to a file.
• matplotlib/Python — when the user requests quantitative charts or complex visualizations that exceed mermaid's capabilities. Produce a .py script that generates the visualization.

Format detection: If the user's request implies a non-prose format, detect it from signal words:

• "present/presentation/slides/deck" → Marp
• "diagram/visualize/map/graph/flowchart" → Mermaid
• "chart/plot/data visualization" → matplotlib
• "compare/table/versus" → markdown table
• "timeline" → mermaid timeline

When in doubt, produce standard prose and offer alternative formats: "I can also present this as a diagram/slides if that would be more useful."

Guidelines

• Always cite which wiki pages informed the answer.
• If the wiki doesn't have enough information to answer well, say so and suggest what sources could fill the gap.
• Don't fabricate information not in the wiki or raw sources.
• If the question is entirely outside the wiki's domain (not a gap — a different subject), say so directly. Do not attempt to answer from general knowledge. State what the wiki covers and suggest the user ask outside the wiki context.
• If the wiki's coverage is asymmetric for the question asked, be transparent about it. An honest "the wiki covers X well but has little on Y" is better than a confident-sounding answer that silently fills gaps.
• When filing an answer as a wiki page, apply the same quality standards and cross-reference conventions as any other page.
• Good answers compound — filing them makes the wiki richer for future queries.
• In navigational mode, keep it cheap — don't read full pages just to produce a results list. Excerpts from grep output are sufficient.