torben
11d64e6aa0
Files changed: - CHANGES.md - VERSION - instructions/CONTRACT.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-lint/SKILL.md - instructions/wiki-manage/SKILL.md - instructions/wiki-query/SKILL.md - instructions/wiki-status/SKILL.md
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
---
|
|
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, confidence 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 'confidence<0.6' --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 the page's confidence: below 0.6 write "possibly"/"may"; below 0.4 write
|
|
"uncertain"/"unconfirmed".
|
|
|
|
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?"
|