kb-note

name	kb-note
description	Extract topics and Q&A from the current conversation and save selected ones as notes
user_invocable	true
arguments	Optional filter or hint about what to extract. Optional: --kb name

/kb-note

You are helping the user capture knowledge from the current conversation into their knowledge base.

KB selection: Parse $ARGUMENTS for --kb <name> flag. If not specified, infer per-candidate:

• For each candidate note, search existing KBs to find which has the most related content.
• Group candidates by their best-fit KB. Present the grouping when showing candidates (e.g., "1. [concept] TCP Congestion Control → general").
• The user can override KB assignment when selecting which notes to save.

Steps

1. Scan the conversation — Review the full conversation history. Identify distinct topics, Q&A pairs, concepts explained, insights shared, or decisions made that would be valuable as knowledge base notes.

2. Present candidates — Show the user a numbered list of potential notes to save:

   Found these topics worth noting:
   
   1. [question] How TCP congestion control works — from your question about networking
   2. [concept] Difference between flow control and congestion control — explained during discussion
   3. [insight] Our project's retry logic may need backoff — observation from debugging session
   

   For each candidate, show: type, proposed title, and where in the conversation it came from.

3. Save all by default — Read save_all_by_default from .kb/config.yaml (default true). When true, save all candidates above without waiting for a selection; the list is shown for transparency, not as a gate. The user may still prune by replying (e.g. "skip 3" / "only 1,2"). When false, ask which to save (e.g. "all", "1,3", "none") via AskUserQuestion and wait.

4. For each candidate to save:

   a. Search existing notes for overlap (Glob + Grep in kbs/<kb_name>/ and other KBs)

   b. If a closely related note exists, show the user and ask: update existing or create new?

   c. Create/update the note in kbs/<kb_name>/ following CLAUDE.md format. Citation paths to references use ../../references/filename.md (two levels up from kbs/<kb_name>/).

   d. Add [[wikilinks]] to related notes in both directions

   e. Update .kb/taxonomy.yaml with any new tags

5. Summary — After saving, show:

   • Files created/updated
   • Tags applied
   • Links added

Note Type Selection

Pick the type based on content:

• question: Clear Q&A exchange in the conversation
• concept: Explanation of a topic or idea
• reference: Information from an external source discussed
• insight: Original observation, connection, or conclusion

Type balance nudge: Before presenting candidates, run python3 .kb/kb-index.py stats --kb <kb_name> to see the current type distribution. If question or insight types are underrepresented (< 15% each), actively look for conversation content that fits those types. For example:

• A debugging discussion often contains an implicit question ("Why does X happen?") worth capturing
• A comparison or tradeoff discussion often contains an insight ("X is better than Y when Z") worth capturing
• Don't force a type that doesn't fit — but do consider whether concept is really the best type or whether question or insight would be more accurate

Rules

• Only extract genuinely useful knowledge — skip small talk, debugging noise, and trivial exchanges
• Prefer atomic notes: if a conversation covered 3 distinct concepts, suggest 3 separate notes
• Respect the user's selection — don't save anything they didn't pick
• If $ARGUMENTS contains a filter, focus extraction on that topic

$ARGUMENTS