Rag architect

Skill AllanWessels/Bratan/skills/rag-architect

Bratan is a self-improving Retrieval-Augmented Generation framework built on an adversarial three-agent loop

Install

npx -y skills add AllanWessels/Bratan --skill rag-architect

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

3.2 KB, as published. Nobody here has run it

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.