Root cause analysis

Status: first cut (FEATURE-410) — this slice ships the heuristic correlation surface and an optional AI narrative. Several signal families and the ML side are deferred; see What's deferred below.

When a checkpoint run fails, knowing which expectation broke is only the first step. Root cause analysis (RCA) correlates the failure with signals PLACEHOLDER Cloud already has — recent profile statistics, anomaly events, schema drift, and cross-run history — and ranks them into a "likely causes" summary so a steward can get to why faster.

RCA is read-only. It computes nothing new and persists nothing: it reads the validation result, the asset's profile runs, recent anomaly events, and the checkpoint's run history, then ranks the correlations. There is no new table and no migration.

Where to find it

On the result detail page of any failed run, a Root cause analysis card renders between the status summary and the trend/expectations cards. It does not appear for passing runs.

What signals feed it

RCA correlates four already-available signal families:

1. Failing expectations + unexpected counts — pulled straight from the result JSON. Each failing check is surfaced with its column, description, and unexpected_count.

2. Failure-pattern classification — by walking the checkpoint's recent run history, RCA classifies the failure as:

   • new — the checkpoint has no prior run, or has always failed since first observed;
   • recurring — the run immediately before this one also failed;
   • regression — a passing run sits between an earlier failure and this one (it was fixed, then re-broke), or the most recent prior run passed.

   The card also shows a small timeline: last passed at and first failed at.

3. Statistical diff — when the result can be linked to a profiled data asset, RCA diffs the two most-recent completed profile runs (the last-passing-vs-current snapshots) on row count and, for each failing column, null rate / min / max / mean. A sharp row-count drop, a null-rate spike, or a shifted value range are the high-frequency real causes of a sudden failure.

4. Anomalies + schema drift — recent AnomalyEvent rows detected around the run time corroborate the data-signal story, and a changed schema_hash between the two profiles flags a schema change (a renamed / retyped / dropped column).

These are ranked deterministically (no ML) by a simple confidence heuristic: schema change > volume drop/spike > null spike > value-range shift > generic expectation failure. A confidence badge (a percentage) precedes each likely cause.

How to read the panel

• Failure pattern + timeline at the top tells you whether this is the first time, an ongoing problem, or a regression — and when it last worked.
• Likely causes is the ranked list. The top item is the most probable cause given the correlated signals; each carries a short explanation and a confidence badge.
• Statistical diff shows the before/after numbers the causes were derived from, so you can sanity-check the conclusion.
• If the result could not be linked to a profiled asset (a legacy or ad-hoc run with no checkpoint), the panel degrades to expectation-only RCA: it still classifies the failure pattern and lists the failing expectations, and says so explicitly rather than showing an empty or broken table.

AI narrative (optional)

If a default LLM config is set for the org, you can click Generate AI summary to add a plain-English diagnosis that explains the ranked causes and suggests a next step. It is off by default to bound LLM spend, and routes through the same SSRF-guarded transport as the rest of the AI features.

When no LLM is configured, the panel shows an inline note linking to Settings → AI instead of failing — the deterministic analysis above is always available regardless.

API

GET /api/v1/organizations/{org_id}/workspaces/{workspace_id}/validation-results/{result_id}/rca

• Readable by any role that can view results (viewer included) — RCA is read-augmentation of a result you can already see.
• Returns {"data": RcaResponse}. A passing result returns {"data": {"applicable": false}}.
• Pass ?include_narrative=true to request the optional AI narrative. The response carries a narrative_status of generated, no_llm_config, not_requested, or error so the client can render the right state without a second round-trip.

See the API reference for the full response shape.

What's deferred

This first cut surfaces the high-frequency data-signal causes. Deferred to follow-ups:

• ML / statistical causal inference (learned causal graphs, Granger-style attribution) — explicitly out of scope per the ticket; the first cut is heuristic ranking only.
• "Recent config changes" timeline from the audit log — audit_events lives in the public schema (a cross-schema query with its own scoping concern), and is the lowest-value/highest-complexity signal.
• Per-failing-row value-distribution diffs (top-values histograms) beyond the scalar column statistics already profiled.
• Async / cached RCA — it is computed synchronously on read today; a worker-precompute + persisted report can come later if latency matters.
• Persisting contributing-factor tags on the result row — the tags are returned in the response, not stored (that would need a migration).
• Cross-asset / lineage propagation — using the asset lineage graph to blame an upstream asset.