rag-architect

name	rag-architect
description	Use this skill when you need high-level guidance on the structure of a RAG pipeline — what stages it should have, what trade-offs each stage makes, when to add or remove a stage. Reach for it for architectural decisions, not numeric tuning.

RAG Architect

This skill is the design-level reference. Read it when you're deciding what stages a RAG pipeline should have, not when you're tuning numbers within a stage.

The two pipelines

RAG is two pipelines that share a vector store:

• Indexing (offline, runs when docs change): load -> parse -> chunk -> embed -> upsert
• Query (online, runs per question): embed -> retrieve -> rerank -> build prompt -> generate -> answer

The key insight binding them: both must use the same embedding model.

Stages in a mature query pipeline

question
  -> [optional] should-we-retrieve classifier  (adaptive)
  -> [optional] query rewrite (resolve "it", "the other")
  -> [optional] query expansion / HyDE / multi-query
  -> embed query
  -> [parallel] BM25 retrieval  +  vector retrieval
  -> RRF merge
  -> [optional] metadata filter
  -> reranker (cross-encoder)
  -> top-N chunks
  -> build prompt with explicit grounding instructions
  -> LLM generates answer with citations
  -> [optional] citation verification pass
  -> answer

Not every pipeline needs every stage. The discipline is: only add a stage if /reports/latest.json shows a failure category that stage addresses.

Stage purposes — when to add each

Stage	Add when
Adaptive retrieval classifier	Latency is a problem, or many user messages don't need retrieval (greetings, follow-ups)
Query rewriting	Failures cluster on conversational follow-ups (what about the other one)
HyDE	Failures cluster on questions whose phrasing is very different from documents
Multi-query	Single-phrasing brittleness; one paraphrase works, another doesn't
Hybrid (BM25 + vector)	Failures involve exact tokens — product names, error codes, version numbers
Reranker	The right chunk appears in top-30 but not top-5
Citation verification	Faithfulness scores low even when retrieval is good
Small-to-big retrieval	Chunks retrieve well but answers are incomplete because surrounding context is missing
Metadata filtering	Questions have temporal or scope qualifiers ("last quarter", "engineering team")
Contextual chunk enrichment	Chunks have ambiguous referents ("it supports up to N")

Anti-patterns

• Adding a stage because it's fashionable, without evidence in the report
• Optimizing generation when retrieval recall is below 0.7
• Adding more chunks to the prompt when the model already ignores some
• Lowering the score threshold to "fix" a regression instead of fixing it

When to step back from this skill

If the problem is numeric (chunk size, k, overlap, rerank model choice), this skill won't help. Use evidence from the report to pick a specific stage's parameter to tune, change it, measure.

If the problem is architectural (no stage exists for this failure mode), this skill is exactly the right reference. Pick the missing stage from the table above and add it.