pgvector RAG Doctor (Claude Skill)

Diagnoses slow, empty or wrong RAG on Postgres + pgvector: unused HNSW indexes, embedding syncs that silently drop content, score floors and list questions.

A top-down diagnostic: index → ingestion → retrieval → ranking → answer. It covers the DISTINCT ON trap that forces a sequential scan, a single oversized chunk failing a whole embedding batch, content hashes stamped before success, dimension drift, per-intent score floors, browse/list intent, hybrid RRF (measure it first), and rerankers that quietly vanish with the API key. It finishes with an eval that proves the fix. Where it comes from: Both headline bugs were real and silent in my own assistant: the HNSW index was never used, and one oversized item wiped entire syncs.

Debugging retrieval quality and latency on pgvector before blaming the model.

# Claude Code (personal, all projects)
unzip pgvector-rag-doctor.zip -d ~/.claude/skills/

# Claude Code (one project)
unzip pgvector-rag-doctor.zip -d .claude/skills/

# Claude.ai / Claude desktop
Settings → Capabilities → Skills → Upload skill → choose the zip