kb-search

KB Search

You perform hybrid semantic and keyword search over the project KB's LanceDB index. Use this skill instead of loading all KB files when searching for a specific concept, term, or constraint.

Prerequisite: kb/.index/ must exist. Run /kb-reindex first if not.

Steps

Step 1 — Pre-condition check

[ -d kb/.index ] && echo "index: present" || echo "index: absent"

If absent:

⛔ No KB index found at kb/.index/. Run /kb-reindex to build the index first.

---

Step 2 — Execute hybrid search

Accept:

• query (string): the search query
• top_k (int, default: 5): number of results to return
• include_all_statuses (bool, default: false): if false, filter out historical and superseded chunks

Hybrid search algorithm:

1. Vector search: embed query with the same model used for indexing. Compute cosine similarity against all chunks in kb_chunks. Retrieve top top_k * 3 candidates.

2. Keyword search: tokenize query. Score each candidate with BM25 against its content field.

3. Score fusion: combine vector score (weight 0.7) and BM25 score (weight 0.3). Re-rank by fused score.

4. Status filter: if include_all_statuses = false, remove chunks where status is historical or superseded. Apply this as a pre-filter on the vector query (not post-fusion) so that top_k * 3 candidates are drawn only from live-doctrine and derived chunks, ensuring top_k results are always available when they exist.

5. Return top top_k results.

---

Step 3 — Format results

Return a ranked list:

KB Search Results for: "<query>"
Showing top N results (historical/superseded filtered)

1. [score: 0.92] kb/properties.md § "Invariants"
   > "All database writes must be wrapped in explicit transactions..."
   Status: live-doctrine

2. [score: 0.87] kb/spec.md § "API Contract"
   > "The API must return errors in the format {error: string, code: int}..."
   Status: live-doctrine

3. [score: 0.61] kb/architecture.md § "Storage Layer"
   > "PostgreSQL is the primary storage backend..."
   Status: live-doctrine