Skip to main content
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.