> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose a failure

> Locate the specific step in the Flow that produced the wrong answer.

Before you can fix a failure, you need to know where it went wrong. Nora's Diagnose pass walks the failing traces and identifies the specific step, retrieval, prompt, or tool responsible.

## Running Diagnose

Automatic when you open a cluster: **Cluster → Diagnose** runs the moment you land on the page.

Also available on a single signal (**Signal → Diagnose**) — useful when you're investigating a one-off before promoting to Improvement.

## Diagnostic categories

Diagnose maps each failure to one or more of:

* **Retrieval issue** — the right chunk wasn't in the top K. Diagnostics agrees with the failure pattern.
* **Grounding issue** — retrieved chunks are stale, contradicted by the graph, or missing citations.
* **Prompt issue** — the prompt doesn't specify the required behavior clearly enough.
* **Tool issue** — a tool wasn't called, was called wrong, or returned wrong data.
* **Memory issue** — the Agent has stale or missing memory for this scope.
* **Model issue** — the model just gets it wrong (usually surfaces when hard cases in the cluster show consistent patterns).
* **Data issue** — the required information isn't in your knowledge base at all.

Some failures have multiple causes. Diagnose ranks them by likelihood.

## Diagnostic evidence

For each hypothesized cause, Diagnose shows:

* Which traces in the cluster support this hypothesis.
* Which specific step in each trace is implicated.
* The confidence score.

Click any evidence line to jump to the trace and see the issue in context.

## Root-cause note

At the end of Diagnose, Nora writes a **root-cause note** — a one-paragraph human-readable summary. Something like:

> **Root cause**: Retrieval misses. In 8 of 10 failing traces, the customer-facing refund policy chunk was not in the top-K results. The chunk exists and is well-formed but sits at position 12-15 due to keyword score being low (the query uses "money back" while the chunk uses "refund").

The note is what a human reads first. It's also what the improvement flow uses to generate proposals.

## Overriding the diagnosis

If you disagree with Nora's diagnosis, click **Suggest different root cause** and pick from a menu, or type your own. Overrides feed back into proposal generation.

Common reasons to override:

* Diagnose blamed retrieval but you know the source docs are outdated (data issue).
* Diagnose blamed prompt but you know the tool is misconfigured (tool issue).

## Multiple root causes

Some clusters have genuinely mixed causes. Diagnose surfaces this as "primary + secondary root causes" and generates proposals for each.

Common pattern: primary is a prompt issue, secondary is a retrieval issue. Both need fixing; usually the primary first.

## Diagnostic history

Diagnose runs are cached per cluster. Re-running is idempotent unless the cluster has new signals since the last run.

Re-diagnose manually if:

* New signals joined the cluster.
* You added new knowledge that might change the analysis.
* You changed a related setting (retrieval preset, prompt, etc.) and want to see if diagnosis shifts.

## When Diagnose fails

Sometimes Diagnose says "I don't know" — the failing traces don't share a common thread that maps to a fixable cause. In that case:

* The cluster is probably too heterogeneous — consider splitting it.
* Or the root cause is external (upstream API changed, model provider updated). Investigate manually.

Nora surfaces this as a "no confident root cause" note; the Improvement flow won't auto-generate proposals.