kb-research-policy

name	kb-research-policy
user-invocable	true
description	Routing and retrieval policy for your personal knowledge base at ~/code/knowledge (or the knowledge-base: path in the active project CLAUDE.md). Use when the user asks about past research, prior notes, captured sources, topics they have studied, or anything that might live in a personal wiki of synthesized notes. Triggers on phrases like "what do we know about", "check my notes", "any research on", "from the KB", "have I looked into", "do I have notes on". Tells you to read the cheap index/ files first, then query via the qmd MCP server (lex for known terms, vec for fuzzy), then open full notes only once the shortlist is small. Also the entry point for answering "is my KB healthy?" — points at just check.

KB Research Policy

Travis maintains a three-layer personal knowledge base. This skill tells you how to find things in it efficiently from any session, regardless of your current working directory.

The three layers:

• raw/ — immutable source archive (web crawls, PDFs, snapshots). Never edit.
• wiki/ — synthesized notes in buckets: sources/, concepts/, reports/, questions/, projects/, playbooks/, dependencies/.
• index/ — cheap one-line-per-entry routing files. Read these first.

For edge cases not covered here, read <kb>/CLAUDE.md and <kb>/AGENTS.md directly.

---

Step 1: Resolve the KB path

Run ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-kb-path.sh and capture its stdout as kb_path. Every subsequent command uses "$kb_path" (double-quoted).

kb_path=$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-kb-path.sh")

If the script exits non-zero, relay its stderr message to the user verbatim and stop — do not guess a fallback path.

---

Step 2: Read the index first

Index files are small (one line per entry) and are the cheapest first hop. Read only the ones relevant to the question. Do not open full wiki notes yet.

Current index files under <kb>/index/:

• sources.md — web pages and docs Travis has read
• concepts.md — synthesized topic pages
• open-questions.md — unresolved inquiries
• playbooks.md — reusable how-to notes
• projects.md — project overviews
• dependencies.md — external tools and libraries
• doc-packs.md — downloaded external doc packs (AUTO-GENERATED)
• freshness.md — last updated_at per external source (AUTO-GENERATED)
• authoritative-files.md — canonical file references

If a listed index file does not exist, skip it silently. Not every KB populates every bucket.

After reading the relevant index files, you should have a shortlist of candidate note IDs. If the index alone gives a confident, complete answer, you may skip Step 3 and answer directly. Otherwise proceed to Step 3 — the hand-maintained index can lag actual note content, so a thin or stale-looking index entry is not itself a complete answer.

---

Step 3: Search with qmd MCP

Use the qmd MCP server to search across notes. Always pass intent so snippets are tuned to the question.

For exact terms and known IDs — use lex (BM25):

mcp__plugin_qmd_qmd__query(
  searches=[{type:'lex', query:'<exact term>'}],
  intent='<what you are looking for>',
  collection='knowledge-wiki'
)

For fuzzy or semantic questions — add vec:

mcp__plugin_qmd_qmd__query(
  searches=[
    {type:'lex', query:'<term>'},
    {type:'vec', query:'<question phrased as prose>'}
  ],
  intent='<what you are looking for>',
  collection='knowledge-wiki'
)

Collection scoping:

• Query both knowledge-wiki and knowledge-external by default — most questions can draw on either.
• Restrict to knowledge-external only when the user explicitly asks what the docs say (upstream documentation only, not Travis's own notes).
• Restrict to knowledge-wiki only when the user explicitly asks what they themselves have concluded (their synthesis only, not raw upstream docs).

Filter low-confidence results with minScore: 0.5 when results are noisy. Treat 0.5 as a starting heuristic, not a fixed constant — adjust it as the corpus grows.

---

Step 4: Open full notes only after shortlisting

Once the index and search results give you a small candidate list, retrieve full notes:

mcp__plugin_qmd_qmd__get(path='wiki/sources/...')
mcp__plugin_qmd_qmd__multi_get(paths=['a.md', 'b.md'])

Do not open full notes before you have a shortlist. Opening notes blindly wastes context and gives worse answers.

---

Health checks

If the user asks whether the KB is healthy:

cd "$kb_path" && just check

This runs scripts/lint-frontmatter (frontmatter validity, wikilink resolution, raw_path existence) and scripts/validate-qmd (retrieval harness).

If content has changed and needs reindexing:

cd "$kb_path" && just refresh

This runs gen-indexes → shape → qmd update → qmd embed → validate-qmd in sequence.

---

Anti-patterns

• Do not open full notes before reading the index and getting a shortlist.
• Do not run qmd CLI commands if the MCP server is available — prefer mcp__plugin_qmd_qmd__*.
• Do not hand-edit index/doc-packs.md or index/freshness.md — they are auto-generated by scripts/gen-indexes.
• Do not substitute a web search for a KB lookup when the KB likely has the answer. Ask Travis if unsure whether a topic is captured.
• Do not write to raw/ — that layer is the ingest archive, maintained by scripts/ingest-web.