Troubleshoot RAG grounding

Before you start

RagCodeGenWorkflow retrieves attune-help context, feeds citation-forced prompts to Claude, and emits answers with source provenance. Issues typically fall into one of three categories: retrieval returning no or wrong passages, the workflow producing output that invents attune features, or the execute call failing outright.

Symptom table

Diagnosis steps

Work through these in order — each step is cheaper than the one that follows it.

1. Reproduce with a minimal execute call

Strip the call to its required arguments and confirm the failure still occurs outside your surrounding application code:

from workflows.rag_code_gen import RagCodeGenWorkflow

wf = RagCodeGenWorkflow()
result = wf.execute(query="<your failing query>")
print(result)

If the failure disappears here, the problem is in how your caller constructs kwargs, not in the workflow itself.

2. Enable DEBUG logging

Before calling execute, raise the log level so the workflow's internal state is visible:

import logging
logging.basicConfig(level=logging.DEBUG)

Re-run your minimal reproduction. Log lines will show which retrieval results were returned and what was passed to the prompt.

3. Check what the workflow received and returned

Inspect the WorkflowResult that execute returns. Confirm that:

• Retrieved passages are present and non-empty.
• The passages contain real API names, workflow names, or CLI commands from attune-help — not placeholder text.
• The result includes provenance or citation fields pointing to source files.

If passages are empty, the retrieval layer upstream of RagCodeGenWorkflow is the likely fault, not the workflow itself.

4. Run the related tests

pytest -k "rag" -v

If an existing test exercises the failing path, its fixtures show exactly what inputs the workflow expects. A failing test also confirms whether you have introduced a regression.

5. Inspect the entry point directly

If the steps above haven't isolated the problem, open src/attune/workflows/rag_code_gen.py and trace the execute method. Look for early returns that could silently drop retrieved context before it reaches the prompt.

Common fixes

Empty or missing retrieval context If execute produces fabricated attune features, the most likely cause is that no passages were retrieved. Verify your retrieval configuration points at the correct attune-help index and that the query you pass to execute is specific enough to match indexed content.

kwargs passed to __init__ or execute are wrong Both RagCodeGenWorkflow.__init__ and execute accept **kwargs. An unexpected keyword argument won't raise a TypeError — it will silently be ignored or override an internal default. Print kwargs at each call site to confirm you are passing what you intend.

Stale environment or cache If the workflow worked previously without a code change, run:

pip show attune   # confirm installed version

Then clear any local caches and retry. A dependency upgrade can alter retrieval behavior or the shape of WorkflowResult.

Prompt injection in retrieved passages The system prompt treats all content inside <passage>...</passage> tags as documentation, not instructions. If your retrieved passages contain directive-looking text and the model is acting on it, confirm that your retrieval layer is wrapping passages in those tags correctly so the system prompt's injection guard applies.

Source files

• src/attune/workflows/rag_code_gen.py

Tags: rag, retrieval, grounding, faithfulness, citation

Unresolved references

Auto-generated by attune-author fact-check. Review and either fix the source code, fix this doc, or add an override.