The underwriting agent receives SUB-1004: a masonry office built in 2001, 20,000 sq ft, sprinklered, wind zone C, no losses. The application says the roof is 9 years old; the roof-data provider says 22 (EV-ROOF-0412). The right recommendation, case UW-004, is escalate, citing R-ROOF-03, the rule for two roof ages that differ by more than 5 years.
Imagine a configuration in which the first stage of retrieval keeps only the 2 nearest passages by vector distance, to save work. The agent runs. It does not escalate. It reports that R-ROOF-03 applies but its current passage was not retrieved, and it makes no recommendation. Every component worked: the guidance corpus holds the whole rule in one chunk (the chunking page fixed that), the version filter kept only current policy, the encoder matched the index. The rule was in the table and never reached the model.
Which stage dropped it? With a single function call named "retrieve", nobody can say. With one record per stage, the answer is one line: the candidate stage kept 2 rows, and R-ROOF-03 was the third nearest. That record per stage is the subject of this page, and so is the order of the stages that produce it.
What this is not. This page follows one query through retrieval up to the passages handed to the answer writer. How those passages are written into the prompt, cited and checked is the grounding page; how to measure whether the right passages came back is evaluation. Fitting retrieval among the other sources of context is covered at context.sammuthu.com.
Retrieval as a chain of narrowing steps#
Recall the primitive. An embedding column holds one vector per row; a vector query compares the query vector with the rows' vectors, ranks the rows by distance and returns the nearest k; the model reads only what retrieval returned. Retrieval is a query. The model reads only what it returns. In production, that one query becomes several steps, because no single ranking is good at everything: vectors blur exact identifiers, keywords miss paraphrases, a fast first ranking is coarse, and the model can read only a few passages.
A retrieval pipeline is the ordered sequence of stages that turns a question into the passages the model reads, each stage receiving the previous stage's rows and passing on fewer. For UW-004: 18 guidance passages in the table, 13 left after the version filter, 13 candidates, 10 after reranking, 5 in the context. Each stage has one job and one number, and each can be inspected on its own.
Before AI. Search engines have worked this way for a long time. A Lucene or Elasticsearch query first matches documents cheaply through the inverted index, applies filters, scores, and can then rescore the top hits with a more expensive function before returning one page of results. A database runs a similar chain inside one statement, and EXPLAIN shows it. A retrieval pipeline is the same idea with vectors in the first stage and a language model at the end.
The seven stages, in order#
The order matters as much as the stages, because each one can only work on what the previous one passed on. Here are the stages as examples/rag-uw/pipeline.py implements them in retrieve, with the job of each.
Diagram: UW-004 through the seven stages: each stage passes on fewer rows
Read left to right, lane by lane. The numbers are from the example's trace for SUB-1004: 18 passages stored, 13 after the version filter, 13 candidates, 10 after reranking, 5 in the context, one recommendation that cites R-ROOF-03. Click a box for its trace field.
- Prepare
- Encode: The question becomes a query vector from the model that embedded the rows.
- Filter: Exact conditions decide which rows may be ranked at all.
- Rank
- Candidates: Dense and BM25 rankings each gather up to 50 allowed rows.
- Fuse: Two ranked lists become one by summing rank-based scores.
- Rerank: A slower scorer reorders the candidates and keeps the top 10.
- Answer
- Select: The context budget decides how many passages go into the prompt.
- Generate: The answer writer cites passage and evidence ids; a person decides.
Encode. The question becomes a query vector, made by the same embedding model and preprocessing as the stored vectors. The example checks this before encoding: the stored embedding_model must equal the encoder's name, or the guard refuses. The embeddings page shows case UW-R06, where a different encoder of the same dimension returns plausible but wrong rows.
Filter. Exact conditions decide which rows may be considered at all: the current policy_version, status, tenant. A filter is not a ranking; a superseded rule or another book's precedent is not "less relevant", it is not allowed. Where the filter sits is a decision with its own section below.
Candidates. One or two first-stage rankings gather a candidate set, the rows the first stage returns for later stages to consider: up to 50 by default here. A dense ranking orders by vector distance; a lexical ranking orders by BM25, the keyword score from the SQL first page. This stage must be cheap per row, because it touches every row that passed the filter, or an index over them.
Fuse. When two rankings ran, their lists are combined into one. The example uses reciprocal rank fusion with k = 60, which adds up a score from each row's rank in each list; the hybrid search page computes it by hand.
Rerank. A slower, more careful scorer reorders the candidates and keeps the top 10. It can afford more work per row because it sees 50 rows, not the whole corpus. The example uses a deterministic stand-in for a cross-encoder; the reranking page covers real rerankers and why their scores are not probabilities.
Select. The context budget, the number of passages placed in the prompt, is applied: 5 here. A threshold can also drop passages that are too weak, so the writer can abstain rather than reason from noise.
Generate. The selected passages, each with its id, go to the answer writer, which cites them. In this example the writer is a script, not a model; the grounding page shows it.
Three budgets, three different numbers#
Three numbers in that chain are easy to confuse, and confusing them leads to wrong decisions about storage and indexes. They are per-query budgets: how many rows each stage passes on for one question.
| Budget | Default here | Stage | What it controls |
|---|---|---|---|
| Candidate set (top k) | 50 | candidates | how widely the first stage looks; recall of the whole pipeline is capped here |
| Rerank top n | 10 | rerank | how many rows survive the careful scorer |
| Context budget | 5 | select | how many passages the model reads |
None of the three is the number of rows stored. The guidance table holds 18 rows; a precedent table might hold 40 or 4,000. Storing more rows changes how much work the candidate stage does, because exact search compares the query with every row that passes the filter, but it does not change how many candidates, reranked rows or context passages a query uses. And adding rows requires vectors for the new rows only: the existing rows keep theirs. This site's own case UW-R10 shows it: the precedent corpus grows from 40 to 4,000 rows, 3,960 new vectors are computed, the 40 existing vectors are unchanged, and the budgets stay 50 / 10 / 5. Whether an index becomes worth building at that size is a measurement, on the scale page.
The budgets do interact in one direction. A row that is not among the 50 candidates can never be reranked, and a row not in the top 10 can never reach the context. So the first budget caps the quality of everything after it, which is the failure in the opening: with a candidate budget of 2, R-ROOF-03 at dense rank 3 was gone before the reranker could see it.
The lab: a funnel of three budgets#
The funnel lab draws the three budgets as stages of a funnel. A row-count control (40, 400, 4,000 or 40,000 precedents) shows that new vectors are computed for new rows only, no row is re-embedded, the budgets do not move, and exact-search work grows with the rows. A collapsible holds a real search_guidance trace for SUB-1004. Toy encoders and synthetic data show how the mechanism works, not how good any model or product is.
The same result without JavaScript, in this example:
| Precedent rows | New vectors computed | Existing rows re-embedded | Candidates / rerank / context | Exact-search distance computations per query |
|---|---|---|---|---|
| 40 | 0 | 0 | 50 / 10 / 5 | 40 |
| 400 | 360 | 0 | 50 / 10 / 5 | 400 |
| 4,000 | 3,960 | 0 | 50 / 10 / 5 | 4,000 |
| 40,000 | 39,960 | 0 | 50 / 10 / 5 | 40,000 |
Only the last column grows with the table. The work column counts distance computations, not milliseconds: toy Python timings are not a benchmark, and this page reports none.
Pre-filter or post-filter: where the filter sits#
The filter stage has a position, and the position changes the result. A pre-filter applies the exact conditions inside the candidate query, before the top k is cut: the ranking only ever sees allowed rows. A post-filter ranks first, cuts the top k, and then removes the rows that fail the conditions. The exact search page shows both in SQL with the tenant filter of case UW-R07; here the question is what the choice does to the whole pipeline.
A post-filter fails two ways. If it is forgotten or broken, disallowed rows flow into the context: a superseded rule, another tenant's precedent. If it works, it removes rows from a list already cut to k, so later stages receive fewer rows than their budget, and nothing tells them. The script below runs the example's pipeline twice on the same query with the same version filter, once as a pre-filter and once as a post-filter, with a candidate budget of 5 to make the effect visible. It is a short file added to a scratch copy of examples/rag-uw that calls only pipeline.retrieve. A successful run proves that the filter's position alone changes how many rows survive; it does not say which position a given database uses internally.
# filter_position.py, run from a scratch copy of examples/rag-uw
# The same pipeline, the same filter, two positions: inside the candidate query (pre) or after it (post).
from pipeline import guidance_retriever, retrieve
current = {"policy_version": "2026.2"}
query = "maximum roof age in wind zone C"
for post in (False, True):
res, trace = retrieve(query, guidance_retriever(), current, candidates=5, mode="dense", postfilter=post)
f = next(t for t in trace if t["stage"] == "filter")
c = next(t for t in trace if t["stage"] == "candidates")
print(f"where={f['where']}: rows {f['rows_total']} -> {f['rows_after']} pass; "
f"candidates kept {c['dense']} of k=5; context {[r['id'] for r in res]}")
where=pre: rows 18 -> 13 pass; candidates kept 5 of k=5; context ['GD-2026.2-R-ROOF-01', 'GD-NOTE-02', 'GD-2026.2-R-ROOF-02', 'GD-2026.2-R-ROOF-03', 'GD-NOTE-01']
where=post: rows 18 -> 13 pass; candidates kept 3 of k=5; context ['GD-2026.2-R-ROOF-01', 'GD-NOTE-02', 'GD-2026.2-R-ROOF-02']
The same 13 rows pass the filter in both runs. With the pre-filter, the 5 candidates are the 5 nearest current passages, and R-ROOF-03 is among them. With the post-filter, the 5 nearest of all 18 passages include two superseded 2025.4 rows; they are removed after the cut, 3 candidates remain, and R-ROOF-03 is not one of them. The query asked about the roof age limit, so the loss here is a related rule; for SUB-1004 it would be the rule the recommendation depends on.
Diagram: The same filter in two positions: inside the candidate query, or after it
Both lanes start from 18 guidance passages and the filter policy_version = 2026.2, with a candidate budget of 5. The pre-filter ranks only the 13 allowed rows and keeps 5. The post-filter ranks all 18, cuts to 5, then removes the 2 superseded rows: 3 remain, and R-ROOF-03 is not among them.
- Pre-filter
- Filter inside the query: Only rows that pass the condition are ever ranked.
- Top 5 of 13: Five allowed candidates, R-ROOF-03 among them.
- Post-filter
- Top 5 of 18: The cut to k happens before the condition is applied.
- Filter after the cut: Removing rows from a list already cut to k starves later stages; forgetting the step leaks.
The rule this site applies: a condition that must hold for every returned row is a pre-filter, inside the query that applies k. Approximate indexes complicate it, because the database itself can end up filtering after a partial index scan. As documented on 2026-11-18, pgvector's README says that with approximate indexes, filtering is applied after the index is scanned, and gives the example that if 10% of rows match and hnsw.ef_search is 40, about 4 rows match on average; since version 0.8.0 it offers iterative index scans to keep scanning. That is case UW-R09, on the ANN page, and its fixes are on the pgvector page. The pipeline-level lesson is the same in every engine: check, in the trace, that the candidate stage returned as many rows as its budget allowed.
In the insurance build. In that build, the Corpus A query applies the structured filter first, thenORDER BY embedding <=> :q LIMIT 8, and widens the filter step by step when fewer than 3 rows come back, reporting each step. Corpus B's first stage filters on provision,status = 'active'and a 36-month lookback, then sorts by distance with a limit of 50 before its feature reranker.
A trace per query#
The opening needed an answer to "which stage dropped it?". A retrieval trace is the record of one query's path through the pipeline: one entry per stage, with what that stage was configured to do and how many rows it received and kept. It is to a pipeline what EXPLAIN ANALYZE is to a SQL statement: the plan, plus what actually happened.
The example writes one with every call. The command below runs search_guidance and find_similar_decisions for SUB-1004 with the trace printed, from a scratch copy of the example. A successful run proves the pipeline is inspectable stage by stage and that the default budgets hold; it does not prove the ranking is good, because the encoder is the toy encoder toy-a@1.
cd rag-uw && /opt/homebrew/bin/python3 pipeline.py --submission SUB-1004 --verbose
search_guidance('roof age limit for wind zone C; roof age on the application and from the provider differ')
1. GD-2026.2-R-ROOF-01 rerank=0.700 dense_rank=1 lexical_rank=1
2. GD-2026.2-R-ROOF-03 rerank=0.700 dense_rank=3 lexical_rank=2
3. GD-2026.2-R-ROOF-02 rerank=0.500 dense_rank=4 lexical_rank=6
4. GD-NOTE-01 rerank=0.500 dense_rank=2 lexical_rank=4
5. GD-NOTE-02 rerank=0.300 dense_rank=5 lexical_rank=3
[
{
"stage": "encode",
"model": "toy-a@1",
"index_model": "toy-a@1",
"dims": 16,
"guard": "checked"
},
{
"stage": "filter",
"filter": "policy_version = current OR attachment of this submission",
"where": "pre",
"rows_total": 18,
"rows_after": 13
},
{
"stage": "candidates",
"mode": "hybrid",
"k": 50,
"dense": 13,
"lexical": 13,
"distance_computations": 13
},
{
"stage": "fuse",
"method": "rrf k=60",
"in": 13,
"out": 13
},
{
"stage": "rerank",
"method": "cross-encoder stand-in",
"in": 13,
"out": 10
},
{
"stage": "select",
"context_n": 5,
"threshold": null,
"selected": [
"GD-2026.2-R-ROOF-01",
"GD-2026.2-R-ROOF-03",
"GD-2026.2-R-ROOF-02",
"GD-NOTE-01",
"GD-NOTE-02"
]
}
]
find_similar_decisions: profiles ['PRF-0218', 'PRF-0206', 'PRF-0091', 'PRF-0172', 'PRF-0197']
approve_side PRE-001 approve 2025.4 score=0.886 bands=7/7 override=False decided under 2025.4; current policy 2026.2 outranks it
approve_side PRE-023 approve 2025.4 score=0.816 bands=6/7 override=False decided under 2025.4; current policy 2026.2 outranks it
approve_side PRE-030 approve 2025.4 score=0.734 bands=5/7 override=False decided under 2025.4; current policy 2026.2 outranks it
decline_side PRE-002 decline 2026.2 score=0.979 bands=7/7 override=True
decline_side PRE-005 escalate 2026.2 score=0.843 bands=6/7 override=False
decline_side PRE-007 decline 2026.2 score=0.672 bands=4/7 override=False
Read the trace top to bottom, as the query traveled. The encode entry says the query and the index used the same model, checked. The filter entry says the filter ran inside the query ("where": "pre") and left 13 of 18 rows: the five superseded 2025.4 rules are gone. The candidate entry says the budget was 50 and only 13 rows existed, so every allowed row was a candidate in both rankings, at a cost of 13 distance computations. Fusion combined the two lists, the reranker kept 10 of 13, and selection kept 5.
Now the ranks in the result lines. GD-2026.2-R-ROOF-03 was third by vector distance and second by BM25; fusion and reranking lifted it to second place. With a candidate budget of 2 and the dense ranking alone, it would have been dropped at the candidate stage, and the trace would show "dense": 2 there. That is the opening, found in one line.
| Trace field | Question it answers |
|---|---|
encode.model, index_model, guard | Were query and rows embedded in the same space? |
filter.where, rows_total, rows_after | Did the filter run inside the query, and how much did it remove? |
candidates.k, dense, lexical, distance_computations | Did the first stage return its full budget, and at what work? |
fuse.method, in, out | Which fusion ran on how many rows? |
rerank.in, out | How many rows did the careful scorer see and keep? |
select.context_n, threshold, selected | Which passage ids reached the model? |
A trace holds ids and counts, not passage text. That keeps it small and safe to store alongside the run: each recommendation can carry its run_id and its trace_id, one trace per run on this site, and a reviewer can replay which evidence the agent saw. Traces and logs as a discipline belong to observe.sammuthu.com.
UW-004 end to end#
The trace ends where generation begins. The example's scripted answer writer takes the five selected passages and the precedents and produces the recommendation. The command below is from a scratch copy of the example; its output is trimmed with "..." where marked. A successful run proves the selected passages are enough for the scripted writer to recommend escalate with the right citation and evidence; it is a script, not a model, so it proves nothing about a model's reasoning.
cd rag-uw && /opt/homebrew/bin/python3 grounding.py --submission SUB-1004
{
"submission_id": "SUB-1004",
"requires_human": true,
"policy_version": "2026.2",
"flags": [],
"conflicts": [
"precedent PRE-001 (approve) was decided under 2025.4; current policy outranks it",
"precedent PRE-023 (approve) was decided under 2025.4; current policy outranks it",
"precedent PRE-030 (approve) was decided under 2025.4; current policy outranks it"
],
"note": "The model recommends; a person decides.",
"context_ids": [
"GD-2026.2-R-ROOF-01",
"GD-2026.2-R-ROOF-03",
"GD-2026.2-R-ROOF-02",
"GD-NOTE-01",
"GD-NOTE-02"
],
"abstained": false,
"recommendation": "escalate",
"citations": [
"R-ROOF-03"
],
"cited_passages": [
"GD-2026.2-R-ROOF-03"
],
"evidence_ids": [
"EV-ROOF-0412"
],
"reasons": [
"The application states a roof age of 9 years; the roof-data provider assessed 22 years (EV-ROOF-0412).",
"The two sources differ by 13 years, more than R-ROOF-03 allows (5): a senior underwriter should review.",
"The model recommends; a person decides."
],
...
}
Follow the ids. The five context_ids are the five passages the trace's select stage named. The citation R-ROOF-03 points to GD-2026.2-R-ROOF-03, which is among them, under policy_version 2026.2. The evidence id EV-ROOF-0412 is the provider's roof age. The three approvals that Corpus B returned were decided under 2025.4, and the writer lists them as conflicts that current policy outranks: a precedent is decision support, never a replacement for current policy. requires_human is true. The model recommends; a person decides.
Where each failure enters#
Because every stage has one job, every retrieval failure enters at one stage, and the fix belongs there. The example's debugger has eight scenarios, each with a broken run, a fixed run and one test that fails on the first and passes on the second. Here is the low-recall scenario from the opening, read through its trace (a short file added to a scratch copy of examples/rag-uw that calls debugger.low_recall). A successful run proves the test separates the two runs and that the trace locates the fault at the candidate stage.
# low_recall_trace.py, run from a scratch copy of examples/rag-uw
# The same UW-004 query with 2 dense candidates and with 50: which stage dropped R-ROOF-03?
from debugger import low_recall
s = low_recall()
for label, run in (("broken (k=2)", s.broken), ("fixed (k=50)", s.fixed)):
cand = next(t for t in run["trace"] if t["stage"] == "candidates")
sel = next(t for t in run["trace"] if t["stage"] == "select")
ans = run["output"]["answer"]
print(f"{label}: candidates k={cand['k']} dense={cand['dense']}; selected {sel['selected']}")
print(f" recommendation={ans['recommendation']} citations={ans['citations']} missing={ans['missing']}")
print("test:", s.test, "| broken passes:", s.check(s.broken["output"]), "| fixed passes:", s.check(s.fixed["output"]))
broken (k=2): candidates k=2 dense=2; selected ['GD-2026.2-R-ROOF-01', 'GD-NOTE-01']
recommendation=None citations=[] missing=['R-ROOF-03 applies but its current passage was not retrieved']
fixed (k=50): candidates k=50 dense=13; selected ['GD-2026.2-R-ROOF-01', 'GD-2026.2-R-ROOF-03', 'GD-2026.2-R-ROOF-02', 'GD-NOTE-01', 'GD-NOTE-02']
recommendation=escalate citations=['R-ROOF-03'] missing=[]
test: The recommendation is escalate and cites R-ROOF-03. | broken passes: False | fixed passes: True
The broken run's writer did the honest thing: it reported the missing rule instead of guessing. The trace shows why the rule was missing: two candidates. The same map holds for the other scenarios.
| Failure | Case | Stage at fault | Where it is explained |
|---|---|---|---|
| Query and index from different encoders | UW-R06 | encode | embeddings |
| Stale policy in the context | UW-R03 | filter | exact search |
| Another tenant's precedent leaks | UW-R07 | filter | exact search, operations |
| A chunk holds half a rule | UW-R08 | chunk (before encode) | chunking |
| Inadequate recall: k too small | UW-004 | candidates | this page; evaluation |
| Unrelated passages fill the context | none | select | grounding |
| The citation names the wrong rule | UW-004 | generate | grounding |
| An instruction inside a retrieved passage | UW-005 | generate | grounding |
The pattern is the point. Most failures that look like "the model got it wrong" entered before the model: at ingestion, at the filter, at the candidate budget. A trace per query turns each of them from a mystery into a line, and a labeled test per failure, measured as on the evaluation page, keeps it from returning.
What frameworks show and what they hide#
Retrieval frameworks wrap the pipeline in one object. As documented on 2026-11-18, the LangChain retrieval page defines a retriever as an interface that takes an unstructured query and returns documents, called with retriever.invoke("query"); its PGVector integration page creates one with as_retriever (its example uses search_type="mmr" and k = 1). LlamaIndex creates a retriever with index.as_retriever(...) and calls retriever.retrieve(query), which returns a list of nodes. These are documented shapes, not run here.
What such an object hides is exactly this page: where the filter runs, what the candidate budget is, whether a reranker ran, how many rows each stage kept. That is not a reason to avoid frameworks; it is a reason to find each of those settings in the framework's documentation and to log a trace around the call. The recipes page puts one retrieval in raw SQL next to the framework versions.
In a coding agent. A coding agent's retrieval is a pipeline too. Encode the question "find where we retry provider calls"; filter to the current branch and the files the user may read; gather candidates from grep and symbol lookup (lexical, exact) and from a vector index of code chunks (semantic); fuse; rerank; keep a few snippets within the context budget. When the agent edits the wrong function, the trace says whether the right file was never a candidate or was dropped at selection.
A checklist for Monday#
| Question | Why it matters |
|---|---|
| Are candidates, rerank top n and context budget three separate settings? | They control different stages; one number cannot serve all three |
| Does every required condition (version, status, tenant) run as a pre-filter? | A post-filter starves or leaks |
| Does the candidate stage return its full budget, and is that checked? | Approximate indexes can return fewer rows after filtering |
| Is the model guard checked at the encode stage? | Same dimension does not mean same space |
| Does every query write a trace with counts per stage? | It names the stage that dropped a passage |
| Can each recommendation be linked to its trace and selected passage ids? | A reviewer can see what the agent saw |
| Is there one labeled test per known failure, run on every change? | Each fix stays fixed |
Tuning the three budgets with labeled queriesMeasure recall at the candidate stage, not only at the end
Each budget is a trade, and each has its own measurement. The candidate budget trades first-stage work for recall: measure recall@50 at the candidate stage, the share of labeled relevant passages present among the candidates, because nothing later can recover a passage that is missing there. The rerank budget trades reranker work for a better ordering of the top: measure how often the relevant passage is in the reranked top 10. The context budget trades the model's attention and the prompt's size for coverage: measure answer correctness and faithfulness as passages are added, on the evaluation page.
Measured per stage, a regression has an address. If end-to-end quality drops and candidate recall is unchanged, the fault is downstream; if candidate recall dropped, no prompt change will fix it. Change one budget at a time, and keep the labeled queries and their results from every run, so a difference can be compared with the run-to-run variation of the system rather than taken at face value.
The filter stage is a permission boundaryBuild it into the query function; test that it cannot be skipped
A tenant or ACL condition is not a relevance signal. If it is applied after ranking, a bug, a refactor or a new caller that forgets the second step returns another book's precedent to the model, and the model can repeat it. Case UW-R07 shows the leak (PRE-003, book-west, returned to a book-east query) and the starvation that a working post-filter causes instead.
The design that holds builds the condition into the one function that issues the candidate query, takes the tenant from the authenticated context rather than from the request, and has no code path that issues the query without it. Two tests guard it: every returned row belongs to the querying tenant, and the candidate stage still returns its full budget when other tenants' rows are the nearest. Deeper defenses against leaks and injected instructions are the subject of guardrails.sammuthu.com.
A latency budget per stage, and where the time usually goesWork grows in different stages for different reasons
Each stage spends time for a different reason, so each is tuned separately. Encoding costs one model call per query, independent of corpus size. The candidate stage grows with the rows that pass the filter under exact search, or with index parameters such as ef_search under an approximate index. Fusion and selection are cheap list operations. Reranking grows with the candidate budget times the cost of one scoring call, which is why a cross-encoder runs on 50 rows and not on the corpus. Generation grows with the context budget and the answer length.
This page reports no timings, because the example's toy Python code is not a benchmark. The practical method is to record the duration of each stage in the trace next to its counts, then look at the 95th percentile per stage, not the average of the whole call. The scale page measures the candidate stage as the corpus grows; the reranking page discusses the reranker's cost against its benefit.
Competing designs: one stage, or manyWhen a pipeline is overkill, and when it is too short
Not every corpus needs seven stages. The insurance build's Corpus B, as its schema records, uses a btree filter plus an exact distance sort with a limit of 50, then a feature reranker, and no ANN index, because each provision's set of precedents is small. A personal notes corpus such as Mnemos's runs dense retrieval only in the code read: no lexical stage, no reranker. Each removed stage is a decision with a reason, and the trace still has the remaining stages.
The opposite mistake is a pipeline too short for its questions: dense only, over a corpus where queries contain exact identifiers such as R-SPRK-01. Case UW-R02 shows the cost: BM25 ranks that rule first, the dense ranking ranks it fifth, and fusion keeps it second. Whether to add a stage is answered the same way each time: a labeled slice of queries that fails without it and passes with it.
In one breath#
A retrieval pipeline is a chain of narrowing queries: encode with the same model, filter exactly inside the query, gather a candidate set, fuse two rankings, rerank, select within the context budget, and generate with citations. Candidates 50, rerank 10 and context 5 are three per-query budgets, none of them the table size, and the first one caps everything after it. A pre-filter keeps every row allowed and the budget full; a post-filter starves or leaks. A trace per query records each stage's counts, so a missing passage, as in UW-004 with two candidates, is found in one line instead of blamed on the model.
SUB-1004 now travels through every stage and comes out as escalate, citing R-ROOF-03, with a trace that shows why. One weakness remains visible in that trace: the vector ranking put R-ROOF-03 third and needed BM25 to lift it, and for an exact identifier such as R-SPRK-01 the vector ranking does far worse. The next page, hybrid search, explains why embeddings blur identifiers and how keyword and vector rankings are fused.