Ragu Build

Assembling a RAGU build

Goal: determine what the user actually needs through a short interview, then produce two artifacts:

• ragu_build.yaml — the recorded decisions and rationale;
• build_<name>.py — a working RAGU build script.

The RAGU library is already documented: every module ships a README.md describing its role in the pipeline and providing examples.

This skill is a decision process and navigation map, not a retelling of that documentation.

Do not read module sources unless explicitly allowed below. Do not summarize whole READMEs. Read narrowly, guided by references/module-map.md.

Conduct the interview in whatever language the user writes in.

Skill resources

All paths under:

• references/
• assets/
• scripts/

are relative to this skill's own directory, not to the user's project root.

Resolve the skill directory using whatever mechanism the current agent environment provides. Never assume that the skill lives inside the user's repository or that its resources are reachable through paths relative to the current working directory.

Phase 0. Inventory

Before asking the user anything, infer everything that can reasonably be discovered from the project.

This removes unnecessary interview questions.

0.1 Read the module map

Read:

references/module-map.md

Use it only as a navigation map for RAGU components and documentation.

0.2 Inspect the project

Inspect relevant project state in one batch where practical.

Corpus

If the user named a data directory, inspect:

• file extensions;
• file count where useful;
• total size.

For example:

find <dir> -type f | sed 's/.*\.//' | sort | uniq -c
du -sh <dir>

This establishes:

• approximate corpus size;
• which file types are present;
• how much of the corpus RAGU can actually ingest.

Do not recursively inspect document contents unless necessary.

Existing infrastructure

Look for already-running or already-configured storage infrastructure.

Useful signals include:

docker ps

and project-local evidence such as:

• qdrant_storage/;
• Qdrant configuration;
• Neo4j configuration;
• existing storage-related compose services.

Use only obvious project configuration. Do not search through unrelated files.

Local model capability

If available, run:

nvidia-smi

Use the result only to determine whether local GPU-backed models are realistic.

Failure or absence of nvidia-smi is not itself an error.

0.3 Credentials boundary

Do not search for:

• API keys;
• credentials;
• .env contents;
• secrets.

Which model provider or runtime the user intends to use is an interview question, not something to discover from private credentials.

0.4 State findings

Before starting the interview, tell the user in one short statement what was discovered and what will be treated as given.

For example:

Your data directory contains about 900 text files totaling ~40 MB. No running vector or graph storage is visible, and a local NVIDIA GPU is available. I'll plan around those facts unless you want to override them.

Anything already established in Phase 0 must not be asked again.

Present inferred facts as correctable facts rather than questions.

Phase 1. Interview

The purpose of the interview is to eliminate incompatible pipeline branches with as few questions as possible.

Interview mechanism

Use the current environment's interactive question mechanism when one is available and appropriate.

Otherwise ask directly in chat.

Do not depend on any specific platform tool name such as AskUserQuestion.

Ask one or two questions at a time.

Never dump the whole interview into a single form or message.

Interview rules

• Phrase questions using example queries and example data, not RAGU implementation terminology.

• Avoid terms such as:

  • "extractive";
  • "abstractive";
  • "hybrid retrieval";
  • "community detection";
  • internal RAGU class names.

Technical terminology may appear in the explanation after the user answers, but not unnecessarily in the question itself.

Q1 is the deliberate exception: whether to build a graph is asked explicitly because this decision dominates both cost and architecture, and many users already know whether they want one.

If they do not know, use Q1b.

After each answer, briefly explain which pipeline branches were eliminated.

Order questions by branching factor.

Use at most six primary questions.

If a question's answer follows from:

• Phase 0;
• an earlier interview answer;
• something the user already stated;

skip it.

Missing answers

Never let an unanswered question stall the deliverable.

If the user:

• skips a question;
• gives an unusable answer;
• selects an equivalent of "I'll specify later" but does not specify it;

ask once more.

If the answer is still unavailable:

1. choose the most defensible default;
2. clearly state that it is an assumption, not a finding;
3. continue.

Every such assumption must appear in all relevant outputs.

In the Phase 2 decision table, write:

ASSUMPTION

in the based on what column.

In ragu_build.yaml, mark it with:

# ASSUMPTION

In build_<name>.py, keep the assumed value as a named constant near the top of the script.

Do not bury assumed values deep inside the implementation.

In the final report, list unresolved assumptions as things the user should verify before the first real run.

An unanswered question should cost one line in the final report.

It must never cost the whole deliverable.

Interview decision order

Exact wording and options live in:

references/decision-matrix.md

section:

Questions

Use that wording when available.

The decision sequence is:

Q1 branching

If Q1 selects a vector-only / flat-index build:

• do not ask Q6;
• skip graph-specific decisions that no longer matter.

Q1b runs only when Q1 is effectively:

not sure

Never ask both Q1 and Q1b as independent decisions.

Phase 2. Decision summary

Before generating any files, show the user a concise decision table with:

The based on what column must identify the source of each decision:

• a specific user answer;
• a Phase 0 finding;
• ASSUMPTION.

Also explicitly state important components that are not included and why.

For example:

No Global engine — none of the example queries asked for corpus-wide themes or summaries. It can be added later without changing the ingestion strategy.

Do not list every conceivable unused RAGU component. Mention exclusions only when they represent meaningful architectural branches.

Wait for user confirmation before Phase 3.

If the user changes one decision:

• revise that decision;
• revise decisions that depend on it;
• do not restart the whole interview unless the change genuinely invalidates all previous answers.

Phase 3. Generation

After the user confirms the decision summary, generate the build.

3.1 Read the decision matrix

Read:

references/decision-matrix.md

in full.

It is the source of truth for:

• exact imports;
• RAGU class names;
• constructor signatures;
• stock build structure;
• component substitutions.

Take every class name and constructor parameter from the matrix rather than from memory.

3.2 Resolve missing component details

If the matrix does not contain enough detail for a selected component:

1. use references/module-map.md to locate the corresponding RAGU module;
2. read only the relevant section of that module's README.md.

Do not read the whole README unless the required information cannot otherwise be located.

Do not inspect source code merely for convenience.