kb-explain

name	kb-explain
description	Synthesize a coherent narrative explanation of a topic from multiple KB notes. Use when the user asks to "explain X from the KB", wants a structured overview/briefing woven from existing notes, or asks "what's the full picture on X".
allowed-tools	Read Glob Grep Bash(python3:*)
user_invocable	true
arguments	The topic to explain. Optional: --kb name to scope to a specific KB

/kb-explain

Synthesize everything the KB knows about a topic into a coherent, structured narrative.

KB routing: Parse $ARGUMENTS for --kb <name> flag. If specified, search only that KB. If not specified, infer the best KB from the topic:

1. Run python3 .kb/kb-index.py quick "TOPIC" --kb <name> for each non-private KB.
2. If one KB has significantly stronger matches, scope to that KB. Mention which KB was selected.
3. If no clear winner or topic spans multiple domains, search unified index.
4. User can always override with --kb <name>.

Steps

1. Find relevant notes — Use multi-query search + manual search:

   • Generate 2-3 reformulations of the topic (synonyms, technical terms, related concepts)
   • Run python3 .kb/kb-index.py search "TOPIC" --multi "REFORMULATION 1" "REFORMULATION 2" [--kb <name>] for fused ranking
   • Run python3 .kb/kb-index.py coverage "TOPIC" [--kb <name>] to assess coverage level
   • Also check: filename and tag matches
   • Body content matches
   • Notes linked from direct matches (follow the wikilink graph)
   • Cast a wide net — include tangentially related notes that add context

2. Read all relevant notes — Read full content of every matched note.

3. Synthesize a narrative — Produce a structured explanation that:

   • Weaves multiple notes into a logical flow (not just concatenation)
   • Starts with the big picture, then drills into specifics
   • Uses transitions that show how concepts connect
   • Cites [[note-name]] inline for every claim sourced from a note
   • Preserves inline citations from the original notes (URLs, file paths, etc.)

4. Context sufficiency & claim verification — Before presenting:

   • Check: does the KB actually have enough coverage to explain this topic? If coverage is "not-covered" or "partially-covered", say so explicitly at the top.
   • For each factual claim in the narrative, verify it traces to a specific [[note]]. If a claim can't be sourced to a note, either remove it or mark it as "Claude's general knowledge, not from KB".
   • If notes contradict each other, present both perspectives with citations.
   • Never silently fill gaps — this is the #1 hallucination vector.

5. Highlight gaps — After the narrative, add a section:

   ## Gaps in KB Coverage
   - {topic area not covered} — Claude knows about X, want to `/kb-question` it?
   - {shallow coverage} — [[note-name]] touches on this but lacks depth
   

   Actively suggest /kb-question <specific question> for each gap so the user can fill them with one click.

6. Show sources — End with a list of all notes used:

   ## Notes Used
   - [[note-a]] — contributed X
   - [[note-b]] — contributed Y
   

Key Differences from /kb-search

/kb-search	/kb-explain
Answers a specific question	Comprehensive topic overview
Concise, targeted	Thorough, narrative
Lists matched notes	Weaves notes into a story
Stays within KB content	Flags gaps and suggests filling them

Saving the Synthesis

After presenting the narrative, offer to save it:

Save this explanation as a synthesis note? (yes / no)

If yes, create a type: synthesis note in the target KB directory (kbs/<kb_name>/). If searching across all KBs, ask the user which KB to save to (default: general).

• Title: "Synthesis: [Topic]"
• type: synthesis
• depends_on: list of all atomic note slugs used to generate this synthesis (for staleness tracking)
• sources: lists all notes used (as ../../references/ paths or note slugs)
• related: links to all atomic notes referenced
• Body is the narrative with [[wikilinks]] preserved
• Synthesis notes are rewritable — they can be regenerated from atomic notes at any time. The atomic notes remain the source of truth.

Dependency tracking: The depends_on field enables python3 .kb/kb-index.py stale-syntheses [--kb <name>] to detect when a synthesis needs regeneration (i.e., when any dependency has been updated more recently than the synthesis). /kb-review checks this automatically.

Rules

• The narrative itself should only contain KB content — clearly separate what the KB says from what's missing
• Don't silently fill gaps with Claude's own knowledge; flag them explicitly
• If the KB has nothing on the topic, say so and suggest /kb-question to start building coverage
• Synthesis notes are the only mutable note type — they can be regenerated from atomic notes

Topic

$ARGUMENTS