---
name: wiki-query
description: Answer a question using the LLM wiki's compiled knowledge - read-only, cites sources, can file a valuable answer back as a new page. Use when the user asks a question about entities, projects, concepts, or anything the wiki might know, or says "query the wiki", "what do we know about X", "search the wiki".
---

# Wiki Query

**Purpose:** Answer a question using the wiki's compiled knowledge.

**Trigger:** User asks a question.

**Before the first `wikitool` call:** [session-setup.md](../session-setup.md).

**Hard rule:** read-only with respect to wiki *content*. Never modify, hand-edit, or scaffold a
page while answering. Two exceptions, both mechanical: step 6 (filing a valuable answer through
`wikitool new`, never by hand) and step 7 (one audit entry via `wikitool log append`). If the
wiki has no confident source, say so - per AGENTS.md's "never file an unsourced answer"
invariant - rather than synthesizing a plausible-sounding answer from general knowledge.

## Steps

1. **Understand the question.** Clarify intent if ambiguous.

2. **Search.** Do **not** read `kb/index.md`; it is a map of counts and pointers, not a
   catalog, and reading the shards costs more than searching them.

   ```bash
   tools/wikitool search "<the user's terms>"
   ```

   Results carry kind, summary and modified date - enough to decide what is worth opening.
   Narrow with predicates when the question is structural rather than lexical:

   ```bash
   tools/wikitool search "backup" --kind entity --subtype system
   tools/wikitool search --field entity_type=system --field '!sources' --sort -modified
   tools/wikitool search --field tags=k8s --limit 30
   tools/wikitool search "Longhorn" --matches      # show the matching lines
   ```

   `search` is read-only and exempt from the iteration budget, so searching again is always
   cheaper than reading more.

3. **Read only the pages the search points at**, then follow their `related:` and `sources:`
   entries. Check `kb/sources/` when the question is about what a specific source said.

4. **Answer and cite.** Name the wiki pages the answer came from, and the sources behind them.
   Hedge to what those sources carry, not to a number - see
   [kb/CONVENTIONS.md § Hedging](../../kb/CONVENTIONS.md#hedging).

5. **Decide what earns a page - before the first `new`.** Name every page you are considering,
   then hold each one on its own against all three criteria: the answer required synthesis
   across several pages, it revealed something not yet written down, and it will be asked
   again. All three, per candidate. A batch is never judged as a batch - one page clearing the
   bar says nothing about the next one.

   A candidate that misses any of the three is not scaffolded. Put one line in the answer
   naming what was considered and why it stays unwritten, and let the user ask for it anyway.
   That is the whole cost of being wrong here in the cautious direction; the other direction is
   a page nobody asked for, which reads exactly like a page the wiki needed and is far harder to
   find again than a sentence in a chat log.

6. **File back what survived.** Scaffold it - `tools/wikitool new ...` - and follow
   `wiki-manage`. Never write the page by hand, and never file an answer no source backs.

7. **Log it.**

   ```bash
   tools/wikitool log append --op query --title "<question>" --body "<outcome>"
   ```

## Decision points

- **Nothing found?** Try the structural query before concluding the wiki is silent - a page may
  exist under different words. Then say the wiki has no confident source, and offer to ingest
  one.
- **Filed a page?** Query does **not** auto-publish. Run `tools/wikitool publish` only if asked;
  the sequence is in [publish-cycle.md](../publish-cycle.md).
- **Several answers filed at once?** That can trip the Mass-Update Gate - see
  [gates.md](../gates.md). The gate is a brake, not the check: it counts files and knows nothing
  about whether any of them earned a page. Step 5 is what decides that, and a batch small enough
  to pass the gate has not been cleared by it.

## wikitool commands used

`search`, `log append`. If filing an answer back: `new`, `xref add`, `sources rebuild-index`,
`index rebuild`, and `publish` only if asked.

## Output

An answer in chat, with citations. Occasionally a new page.

**Example queries:**

- "What projects use MQTT?"
- "Show me the architecture of HA Integration"
- "Compare gdeploy and plugnburn-edl"
- "What decisions were made about E3DC integration?"