kb-research

name	kb-research
description	Agentic research loop that deeply investigates a topic via web search and saves findings as atomic notes
user_invocable	true
arguments	Topic to research. Flags: --depth shallow/medium/deep, --checkpoint plan/each/end, --kb name

/kb-research

Agentic research loop. Given a topic, plan a research agenda, iteratively search the web, follow leads, fill gaps, and produce comprehensive atomic notes.

Parse Arguments

Extract from $ARGUMENTS:

• Topic: the research subject (required)
• --depth: shallow | medium | deep. When not given, use research_depth_default from .kb/config.yaml (default: deep).
• --kb: target KB name. If not specified, infer the best KB (see below). Verify the KB exists in kbs.yaml. Save notes to kbs/<kb_name>/.
• --checkpoint: when to pause for user input (default: plan+end)
  • plan — pause after planning, then run autonomously until synthesis
  • each — pause after each sub-question to show findings and ask to continue/redirect
  • end — no pauses, full autonomy, show everything at the end
  • Combine with +: plan+end (default), plan+each, etc.

Depth Levels

Depth	Follow-up rounds per question	Behavior
shallow	1	One round of search per question, follow up on gaps once
medium	2	Follow up on gaps twice per question
deep	Until diminishing returns, max 10	Keep researching until new searches add little value, hard cap at 10 rounds total across all questions

KB Inference

If --kb was not specified, infer the target KB before planning:

1. Read kbs.yaml to get all non-private KBs with their descriptions.
2. Run python3 .kb/kb-index.py search "TOPIC" --kb <name> for each non-private KB to see which has the most relevant existing notes.
3. Also consider the KB descriptions — if the topic clearly fits a domain KB's description, prefer that KB.
4. Propose the KB in the research plan: "Target KB: <kb-name> (strongest match: N related notes). Change? (or specify a different KB)"
5. If no KB has relevant notes and the topic doesn't match any domain description, default to general.

This inference happens once before Phase 1 and is confirmed by the user during the plan checkpoint.

Phase 1: PLAN

1. Check existing KB — Search all KBs (kbs/*/) for what the KB already knows about this topic. Read any relevant notes.

2. Break topic into research questions — Decompose the topic into 3-7 specific, answerable sub-questions. Consider:

   • What are the core concepts?
   • What are the key debates or trade-offs?
   • What are the practical implications?
   • What does the KB already cover vs. what's missing?

3. Present research plan to the user (if plan checkpoint is active):

   ## Research Plan: [Topic]
   
   Already in KB:
   - [[existing-note-1]] — covers X
   - [[existing-note-2]] — covers Y
   
   Research questions:
   1. [question 1] — why this matters
   2. [question 2] — why this matters
   ...
   
   Depth: <resolved depth> (e.g. deep — research until diminishing returns, max 10 rounds)
   Checkpoints: after plan + at end
   
   Proceed? (yes / adjust questions / change depth)
   

4. Wait for user approval if checkpoint is active. User can adjust questions, depth, or add/remove topics.

Phase 2: RESEARCH LOOP

For each research question, run the research loop:

1. Search — Use WebSearch to find relevant sources for the question.

2. Read & evaluate — Use WebFetch to read promising results. Assess:

   • Is this source credible and substantive?
   • Does it answer the question or part of it?
   • Does it raise new questions worth following?

3. Save useful sources — Write fetched content to references/ as markdown files with slugified names. Format:

   # Title
   Source: https://original-url
   Fetched: YYYY-MM-DD
   Source-Type: primary | secondary | opinion | unverified
   
   ## Key Content
   (structured summary of findings)
   

   Classify each source:

   • primary: original data, official post-mortems, academic papers, protocol/product documentation
   • secondary: analyses based on primary sources (firm reports, technical breakdowns, reputable journalism)
   • opinion: tweets, blog opinion pieces, community commentary
   • unverified: news articles, aggregator summaries

   Only save sources that are substantive and worth citing. These files become the citation targets for notes.

4. Extract findings — Note key facts, claims, frameworks, and insights. Track which source each finding comes from.

5. Identify gaps — What's still unclear? What follow-up questions emerged?

6. Follow up — If depth budget allows, search for gap-filling information. Decrement the follow-up counter.

7. Checkpoint — If each checkpoint is active, pause after each question:

   ## Question 1: [question]
   
   Findings so far:
   - [key finding 1] (source: ...)
   - [key finding 2] (source: ...)
   
   Gaps remaining:
   - [gap 1]
   
   Continue to question 2? (yes / redirect / add question / stop here)
   

Concurrency Decision

Claude decides whether to research sub-questions concurrently or sequentially:

• Concurrent (via subagents): when questions are independent and answers to one won't inform another. Prefer this for breadth-oriented research.
• Sequential: when later questions build on earlier findings, or when the topic is narrow and each answer reshapes the next question. Prefer this for depth-oriented research.

State the choice and reasoning in the plan.

Phase 3: SYNTHESIS

After all questions are researched:

1. Compile findings — Organize all findings across all questions. Identify:

   • Atomic concepts worth their own note
   • Overarching themes or frameworks
   • Contradictions or debates between sources
   • Connections to existing KB notes

2. Present proposed notes — Show the user a numbered list of proposed notes:

   ## Research Complete: [Topic]
   
   Sources saved to references/:
   - references/source-1.md
   - references/source-2.md
   
   Proposed notes:
   0. [reference] Research Hub: [Topic] — hub linking all notes from this research
   1. [concept] [Title] — [one-line summary]
   2. [concept] [Title] — [one-line summary]
   3. [insight] [Title] — [one-line summary]
   ...
   
   Gaps not fully resolved:
   - [gap] — couldn't find definitive answer
   

3. Save all by default — Read save_all_by_default from .kb/config.yaml (default true). When true, proceed to create all proposed notes without waiting for a selection — the list above is shown for transparency, not as a gate. The user may still prune by replying (e.g. "skip 3" / "only 1,2") before or as creation proceeds. When false, instead append "Which notes to save? (all / 1,3,5 / none)" and wait for the user's selection.

4. Create notes — For each selected note: a. Contradiction check: Run python3 .kb/kb-index.py search "NOTE_TITLE" --kb <kb_name> to find similar existing notes. If the score is at or above similarity.contradiction_overlap in .kb/config.yaml, read those notes and check for conflicting claims. If contradictions found, ask user: reconcile, update existing, or create separate with link? b. Dedup check: If the similar-note score is at or above similarity.dedup_threshold in .kb/config.yaml, it likely covers the same concept — suggest updating the existing note instead of creating a duplicate. c. Create/update following CLAUDE.md format. Assign epistemic_status based on source quality:

   • verified if backed by primary sources (original data, official post-mortems, academic papers)
   • likely if backed by credible secondary sources
   • speculative if based on inference or extrapolation
   • disputed if conflicting claims exist
   • opinion if the note contains the author's judgment d. Cite all sources inline via local reference files — every claim must trace back to [display text](../../references/filename.md) (two levels up from kbs/<kb_name>/). The reference file contains the external URL. Never cite external URLs directly in notes if a reference file exists for that source. e. Add [[wikilinks]] to the research hub and related notes, in both directions f. Define terms inline — on first use of a technical term not commonly known, add a brief parenthetical definition. Link to a concept note via wikilink only if one exists. g. Rebuild index: After creating all notes, run python3 .kb/kb-index.py build --incremental --kb <kb_name> to update the search index (only re-indexes changed notes).

5. Create research hub note — A reference-type note that:

   • Summarizes the research topic and key findings
   • Lists all sources in sources frontmatter
   • Links to all created notes via [[wikilinks]]
   • Record gaps in frontmatter — add a gaps: list to the YAML frontmatter with each unresolved gap as a string. This makes gaps machine-readable and queryable via python3 .kb/kb-index.py gaps research. Example:

     gaps:
       - "Topic X: specific unanswered question"
       - "Topic Y: needs deeper investigation"
     

   • Also list gaps in the body under a ## Research Gaps section for human readability

6. Update taxonomy — Add new tags to .kb/taxonomy.yaml.

7. Final summary:

   • Notes created/updated
   • Sources saved
   • Tags applied
   • Links added
   • Gaps flagged for future research

Rules

• Never fabricate sources — every citation must point to a real source that was actually read
• Never edit or delete existing files in references/ — only write new files
• Atomic notes — one concept per note, even from a single source
• Track provenance — maintain a clear chain from claim → note → source throughout
• Respect depth limits — don't exceed the follow-up budget for the chosen depth level
• Respect checkpoints — always pause when the user's checkpoint setting says to
• Be honest about gaps — if something couldn't be resolved, say so rather than guessing

Topic

$ARGUMENTS