Spec: retriever rewrite

[adamjohnwright]

First use of Spec Kit, on the decision three open PRs are queued behind (#116, #133, and the config work in #112/#151).

This is a specification, not an implementation. It exists to make four decisions explicit and cheap to make.

What it records

What the retriever does today, including the five places it reaches into LangChain internals — with line numbers, so the table can be re-checked rather than trusted:

location	what it does
csv_chroma.py:143	subclasses MultiQueryRetriever
csv_chroma.py:59,144	overrides a required field to None via SkipJsonSchema
csv_chroma.py:192-194	builds a throwaway MultiQueryRetriever to steal its .llm_chain
csv_chroma.py:200	assigns _retrievers outside pydantic
csv_chroma.py:206	instantiates EnsembleRetriever(retrievers=[]) to borrow one method

Those are why the LangChain upgrade is blocked.

The four open decisions

• D1 — replace SelfQueryRetriever with plain semantic search? Helia's proposal. It removes 20 LLM calls per message and the component most likely to break on 1.x. But Retrieval: replace SelfQueryRetriever with a plain semantic retriever? #171 measured SelfQuery as stable run to run, agreeing with plain vector on only 0.48 of documents and 0.19 of positions — so this is a real behaviour change, not the removal of noise. Those numbers predate the Retrieval: duplicate documents consume half the top-k budget on reactions #169/Retrieval: BM25 and vector results are concatenated, not fused #170 fixes and want recapturing.
• D2 — budget per collection or global? Per collection guarantees each contributes; global is simpler but lets one crowd the others out.
• D3 — documents or tokens? feat(retriever): add token-aware context truncation to cap documents passed to LLM #139 argued tokens, correctly. Measured 1.6x spread across 40 documents, but at 7% of the context window it is not currently binding.
• D4 — does multi-query expansion stay? One LLM call that multiplies every downstream retrieval by five. Its value has never been measured.

Notes

Every factual claim was checked against the code rather than written from memory, which caught two errors: the mypy baseline holds four retrievers.*.rag entries, not three — userguide arrived with feature/userguide-qa — and the reach table needed line numbers.

Success criteria are observable rather than aspirational: no LangChain internals remain, sync and async agree on identical inputs, two callers get different budgets in the same process, and the four mypy baseline entries are deleted rather than carried forward.

Checked against .specify/memory/constitution.md; all six articles are addressed.

Nothing is implemented here. The next step is D1–D4, then /speckit-plan.

🤖 Generated with Claude Code