| name | index |
| description | Reindexes KB for semantic search via vector store (Qdrant). Triggers: reindex KB, rebuild index, vector reindex, refresh embeddings. |
| effort | low |
| disable-model-invocation | true |
| argument-hint | [path or scope] |
| allowed-tools | Bash |
Knowledge Base Indexing
$ARGUMENTS
Reindex the knowledge base for semantic search.
Prerequisite: This command requires a vector store (e.g., Qdrant) and an indexing pipeline configured for your project. If not configured, this command provides guidance on setup.
Usage
/index # Incremental index (detect changes)
/index --full # Full rebuild
Execution
Direct Execution
make index
make index-full
Docker Execution
docker exec {app-container} make index
docker exec {app-container} make index-full
Change Detection
The indexer uses content hashing to detect changes:
| Scenario | Action |
|---|
| New document | Index |
| Changed content | Reindex |
| No changes | Skip |
| Deleted document | Remove from index |
Frontmatter Validation
Before indexing, ensure all KB documents have valid frontmatter:
---
title: "Document Title"
service: {service-name}
category: reference|howto|procedures|troubleshooting|decisions|best-practices
tags: [tag1, tag2]
last_updated: "YYYY-MM-DD"
---
Troubleshooting
| Problem | Solution |
|---|
| Index not updating | Check file timestamps, run full rebuild |
| Missing documents | Verify frontmatter is valid |
| Slow indexing | Check embedding service performance |
| No vector store | Set up Qdrant or compatible vector DB |
Rules
- MUST require explicit user permission before running
make index or make index-full — never self-trigger
- NEVER trigger a full rebuild to "clean up" unless the user asked for it
- CRITICAL: validate KB frontmatter before indexing — abort on invalid documents rather than indexing a broken state
- MANDATORY: respect change-detection hashes; do not force reindexing of unchanged documents
Gotchas
- Content-hash change detection keys on the file's content AND path. A moved document (same content, new path) looks new to the indexer — both the old path vector and the new one will exist until a full rebuild. Plan a full rebuild after mass reorganizations.
- Deleting a document on disk does not automatically remove its vectors from Qdrant; the indexer emits tombstones only if run with a directory scan. Without
--delete-missing, orphan vectors stay for weeks.
- Embedding providers rate-limit by requests-per-minute AND by tokens-per-minute. A reindex of 1000+ docs hits the token cap first and stalls silently — watch for 429s in the indexer log before concluding "slow indexing".
make index-full truncates the collection before re-embedding; if the embedding job crashes mid-way, the collection is left partially populated with no query-time indicator of the gap.
When NOT to Use
- For searching the KB — use
/research-mastery or call smart_query() via the rag-mcp tool
- For fixing indexing bugs — use
/debug on the indexer pipeline
- To evaluate RAG quality after reindexing — use
/evaluate
- When no vector store is configured — document the gap, do not invent one