AGENT SKILL

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
所属仓库
cwik-tech/octopus
最近更新
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

cwik-tech
cwik-tech/octopus

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.

★ 0
cwik-tech
cwik-tech/octopus

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.

★ 0
cwik-tech
cwik-tech/octopus

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.

★ 0
cwik-tech
cwik-tech/octopus

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.

★ 0
cwik-tech
cwik-tech/octopus

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.

★ 0
cwik-tech
cwik-tech/octopus

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.

★ 0