kb-query

name	kb-query
description	Query the knowledge base — ask a question and get a synthesized answer with citations saved to output/. Supports --kb <name> for cross-project queries. Use when the user wants to query, ask, search, or look up something in their KB. Also triggers on "kb-query" or "/kb-query".

kb-query

Ask a question against the knowledge base and receive a synthesized answer with citations. This is the ONLY command that uses readonly mode and supports MRU fallback for cross-project queries.

This command never modifies wiki/ or raw/. Output is written only to output/.

Arguments

• <question> — The question to answer (required).
• --kb <name> — Query a specific KB by name (optional). If omitted and not inside a KB, falls back to most recently used KB.

Step 1: Resolve KB (Readonly)

python3 ~/.config/kb/scripts/kb_resolve.py --mode readonly

If --kb <name> was specified:

python3 ~/.config/kb/scripts/kb_resolve.py --mode readonly --kb "{{KB_NAME}}"

This is the only command that uses --mode readonly. If resolution fails and no --kb was given, attempt MRU fallback:

python3 ~/.config/kb/scripts/kb_registry.py most-recent

If MRU also fails, abort: "No knowledge base found. Run kb-bootstrap to create one, or use --kb <name>."

Step 2: Find Candidate Pages

Run the related-content finder with the user's question:

python3 ~/.config/kb/scripts/kb_find_related.py "{{KB_ROOT}}" --query "{{QUESTION}}" --top-k 15

Collect the returned list of candidate wiki pages ranked by relevance.

Step 3: Read Index and Candidates

1. Read {{KB_ROOT}}/index.md for structural overview.
2. Read each candidate page returned in Step 2.
3. Note the confidence and stability of each page — use these to weight the answer.
4. Note human_reviewed status — these carry higher trust.
5. Check for contradictions fields — if candidates contradict each other, flag this in the answer.

Step 4: Synthesize Answer

Compose an answer that:

• Directly addresses the user's question.
• Cites sources using [[wikilinks]] to wiki pages.
• Includes confidence qualifiers for uncertain claims (e.g., "According to [[page]] (confidence: 0.6)...").
• Notes contradictions between sources if any exist.
• Distinguishes between well-supported conclusions and tentative inferences.

Structure the answer with:

• A direct answer paragraph.
• Supporting evidence with citations.
• Caveats or contradictions (if any).
• Related pages for further reading.

Step 5: Save to Output

Generate an output filename: output/<YYYY-MM-DD>-<slug>-<HHmmss>.md

• <slug>: lowercase, hyphenated, max 50 chars, derived from the question.
• <HHmmss>: current time for uniqueness.

Write the file:

---
query: "{{QUESTION}}"
date: {{DATE}}
kb: "{{KB_NAME}}"
candidates_searched: {{N}}
candidates_cited: {{M}}
---

# {{QUESTION}}

{{SYNTHESIZED_ANSWER}}

## Sources

| Page | Confidence | Stability | Human Reviewed |
|------|-----------|-----------|----------------|
| [[page-1]] | 0.8 | stable | false |
| [[page-2]] | 0.6 | evolving | true |

Step 6: Append Log

Add a row to log.md:

| {{DATE}} | query | "{{QUESTION}}" → output/{{FILENAME}} ({{N}} sources consulted) |

Step 7: Update Registry

python3 ~/.config/kb/scripts/kb_registry.py update-access --name "{{KB_NAME}}"

Final Output

Present the synthesized answer directly to the user (do not just point them to the file). Also print:

• Path to the saved output file.
• Number of sources consulted.
• Any low-confidence claims flagged.
• Any contradictions surfaced.
• Suggestion: "Run kb-promote to save this answer to the wiki" (if the answer is substantive).