rag-topology-design
End-to-end retrieval topology design — runs a necessity gate before proposing any retrieval layer, then works ingestion, chunking, embedding, index, hybrid composition, reranking, context assembly, and freshness in order, justifying each layer against actual query shapes.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rag-topology-design
- description
- End-to-end retrieval topology design — runs a necessity gate before proposing any retrieval layer, then works ingestion, chunking, embedding, index, hybrid composition, reranking, context assembly, and freshness in order, justifying each layer against actual query shapes.
03 SKILL.md 正文
RAG Topology Design
Purpose
Produce a defensible retrieval architecture, or a defensible refusal to build one. Most retrieval systems are assembled by picking a vector database first and reverse-engineering the rest. This skill inverts that: establish whether retrieval is warranted, then derive each layer from the query shapes the system must serve.
When to use
Every session where retrieval is proposed, assumed, or already built. Run it even when the brief opens with "our RAG pipeline" — especially then.
Step 0 — The necessity gate
Before any topology work, answer three questions:
| Dimension | Question | Retrieval warranted when |
|---|---|---|
| Size | How many tokens is the full corpus? | Exceeds a comfortable context budget by a wide margin |
| Volatility | How often does content change? | Changes faster than a curated context can be maintained |
| Heterogeneity | How varied are the queries? | Queries hit unpredictable, non-overlapping slices |
Decision rule. Fewer than two dimensions failing means curate the context and do not build retrieval. Say this plainly and propose the curated alternative — a hand-assembled context, a static index of summaries, or a routing layer over a handful of documents.
If the gate fails but the team is committed to retrieval anyway, name the cost explicitly: infrastructure, evaluation burden, latency, and a new failure mode where the system confidently retrieves the wrong passage.
Layer 1 — Ingestion
- What are the source formats, and what fidelity is lost converting them?
- What structure exists in the source (headings, tables, code blocks, threading) that must survive?
- What metadata is available at ingestion that could later filter or boost retrieval?
- What is the ingestion cadence, and is it batch or streaming?
Metadata captured at ingestion is nearly impossible to recover later. Enumerate it now.
Layer 2 — Chunking
Chunk boundaries follow the shape of the questions, not the shape of the files.
- What is the typical answer span — a sentence, a paragraph, a section, a whole document?
- Do queries need cross-boundary context, and if so, does overlap or parent-document retrieval serve it better?
- Are there natural semantic boundaries (sections, functions, turns) that should be respected?
- What breaks when a chunk splits mid-table, mid-code-block, or mid-argument?
Name the chunking strategy, the size, the overlap, and the reason for each. "512 tokens with 50 overlap" without a reason is a default, not a decision.
Layer 3 — Embedding
- What is the domain vocabulary, and does a general-purpose model cover it?
- What dimensionality, and what does the extra dimension cost in index size and query latency?
- Is the query distribution symmetric with the document distribution, or asymmetric (short query, long passage)?
- What is the max sequence length, and does it accommodate the chosen chunk size?
- What is the cost and latency of embedding the full corpus, and of re-embedding it when the model changes?
Model choice binds the index. Changing embedding models later means a full reindex — treat it as a migration, not a config change.
Layer 4 — Index
- Approximate or exact nearest neighbor, and what recall loss is acceptable?
- What is the index build time and memory footprint at target corpus size?
- Does the workload need metadata filtering, and does the index support it without collapsing to a scan?
- Is the deployment target server, edge, or local? Local-first constrains index size and build compute severely.
Layer 5 — Hybrid composition
Add a retrieval path only when a query class systematically fails on existing paths.
| Path | Serves | Costs |
|---|---|---|
| Dense | Semantic similarity, paraphrase, conceptual match | Embedding compute, weak on rare exact terms |
| Sparse (BM25 or similar) | Exact terms, identifiers, rare vocabulary, negation | Index maintenance, weak on paraphrase |
| Graph traversal | Multi-hop relations, provenance chains, structural queries | Schema dependency, traversal latency, depth budget |
For each path included, state the query class it serves and what breaks if it is removed. For fusion, name the method (reciprocal rank fusion, weighted score, cascade) and how the weights will be tuned — an untuned fusion weight is a guess.
Graph traversal has a boundary: the traversal strategy, depth budget, and cost are retrieval decisions. The entity and relation schema is not — route that to the ontology owner.
Layer 6 — Reranking
- Does the first-stage retrieval have a recall problem or a precision problem? Reranking fixes precision only.
- What is the rerank latency at target k, and does it fit the budget?
- Cross-encoder, LLM-as-reranker, or heuristic — and what does each cost per query?
- What k goes in and what k comes out?
A reranker over a first stage with poor recall is expensive polish on a hole. Fix recall first.
Layer 7 — Context assembly
- How many chunks reach the model, and in what order?
- Is there deduplication, and does it operate on text or on source?
- Are chunks presented with provenance, and does downstream output need to cite them?
- What happens when retrieved content contradicts itself?
- What is the assembled context size against the total budget, and what else competes for that budget?
Layer 8 — Freshness and reindexing
Decide this alongside the index, never after.
- What is the acceptable staleness contract, stated in time?
- Full rebuild, incremental upsert, or dual-write with cutover?
- What happens to in-flight queries during a rebuild?
- How are deletions propagated, and is there a tombstone requirement?
- What triggers a full re-embed, and what does it cost in time and money?
Output
A layer-by-layer topology where every layer names the query class it serves and the cost it adds. Any layer that cannot name both should be removed. Pair the topology with the evaluation harness from retrieval-evaluation-harness before treating it as decided.
04 同仓库更多 Skills
twenty-year-land-plan
Apply the Bren discipline of evaluating every land and development decision on a twenty-year horizon, with a comprehensive plan for how the land, the community, and the surrounding public infrastructure evolve together. Deals optimized for a five-year exit are structurally different from deals that compound across generations; insist on knowing which kind you are making. Use when evaluating land, entitlements, master-planned development, or phasing decisions, and when separating five-year exit deals from generational holds.
thematic-gut-check
Apply the Gray discipline of identifying the structural theme behind every real estate deal, testing where that theme sits in its capital-flow lifecycle, and insisting that deals without a named theme — or deals late in a crowded theme — clear a higher bar. A mediocre deal in a strong theme usually beats a clever deal in a weak one. Use when naming the structural thesis behind a deal, judging whether that theme is early or crowded, and setting the bar the deal must clear.
supply-pipeline-gut-check
Apply the Zell discipline of grounding every real estate thesis in the local supply pipeline. Demand counts over adjectives — units under construction, units permitted, units proposed — and convert them into a forward absorption schedule. A deal that ignores the pipeline is a bet on a market you have not actually studied. Use when validating a market thesis, forecasting absorption and rent growth, or counting units under construction, permitted, and proposed.
ruin-scenario-mapping
Apply the Taleb discipline of identifying, for every real estate deal, the specific chain of events that produces ruin — permanent, unrecoverable capital loss — and verifying that no single such chain has non-trivial probability. Deals with any plausible ruin path must be restructured or abandoned. Use when sizing leverage, testing refinancing, covenant, and liquidity risk, or checking whether any single failure chain can permanently wipe out the position.
revenue-cost-architecture
Design a venture's revenue streams, pricing logic, cost structure, and unit economics so the business model has a coherent theory of value capture, not just value creation. Use after the value proposition and customer segment are set and before financial projections, when choosing a pricing model, calculating contribution margin or CAC payback, or checking whether the unit economics hold at scale.
replacement-cost-stress-test
Apply the Buffett discipline of pricing every real estate asset against the cost to rebuild it from scratch. The ratio of purchase price to replacement cost sets a ceiling on long-run downside: below replacement cost, new supply cannot profitably undercut you; at or above it, you are buying a liability disguised as an asset. Use when setting a purchase price, judging downside protection, or testing how exposed an asset is to newly built competing supply.