Series
9 parts
A 1080-line file produces 27 chunks. Most boundaries fall mid-function, with no awareness of code structure. Here's exactly what gets lost — and why it matters for search quality.
One failure is a chunking problem. The other is a vocabulary gap that better chunking can't fix. Here's what the scores reveal about code RAG's limits.
The function name query score jumps from 0.49 to 0.71. A function that was buried at rank 9 moves to rank 3. Here's what changes when each function gets its own chunk — and why the extractor ended up being a bigger decision than expected.
The error query went from not found to visible — sometimes. Sampling the same real model call eight times on the same function shows the fix works about half the time, not reliably. Here's the honest version of that story.
For the run where the description happened to name the error, hybrid search pushes the target from rank 8 to rank 2. For the run where it didn't, hybrid search does nothing at all — there's no token to boost. Both are real, measured outcomes of the same technique.
This technique didn't exist anywhere in the codebase before this post. Built it for real, measured it for real, and it makes the hardest query worse, not better. Here's exactly why, and what a two-stage retrieval architecture can't recover from.
Upsert is insert-or-update by ID. It doesn't delete old chunks when a function is refactored. Without a registry, stale vectors accumulate silently until your LLM is reading code that was deleted six months ago.
Three operations that sound similar. They are not. Each has different triggers, different costs, and different consequences if you get them wrong — including one mistake this exact codebase's own index actually made.
Two ways to know your RAG is working: a recall harness you run before you ship, and chunk-level tracing that shows what actually retrieved in production. Neither replaces the other — and this project already had half of each, in a shape worth being precise about.