## TL;DR

Failures cascade: one bad upstream model fails its own tests and then every downstream relationships and consistency test that reads it. Triage by DAG order: find the earliest failing test whose upstream tests all pass, fix that one first, and rerun before touching the rest. Most of the five will clear without edits once the root is fixed.

```text
agent couldn't tell which of 5 failing tests was the root cause
```

## Use this when

- dbt build reports several failing tests (for example 5) across related models
- an agent or human cannot tell which failure to fix first
- several failures share an upstream model or a common column

## Not for this skill when

- the failures are on unrelated models with no shared lineage, triage them as independent problems
- all failures trace to a warehouse outage window, wait and rerun instead of editing tests
- one test fails alone, just fix it directly

## Steps

1. Map failures to the DAG: list each failing test with its model, then order the models topologically using dbt ls or the manifest depends_on data. Mark which failing models are ancestors of other failing models.
   Verify: failures are ordered by lineage with ancestors identified.

2. Inspect the earliest ancestor failure first: read its failing rows from the store_failures table or by running its test query. Form the root cause hypothesis (bad source rows, a join change, a renamed column).
   Verify: the earliest failure has a concrete, evidenced cause.

3. Check symptom consistency: verify that the downstream failures are explained by the root (for example orphan keys downstream match the keys broken upstream). If one downstream failure is not explained, flag it as a possible second root.
   Verify: each remaining failure is classified as symptom or independent.

4. Fix the root cause in the model or source handling, rerun dbt build for the affected subgraph, and confirm the symptom tests pass without edits.
   Verify: the build is green for the subgraph, or only genuinely independent failures remain.

## Variant phrasings

### root is a source data problem
Sometimes the earliest failure correctly reports bad source data. The fix is then upstream of dbt (loader or source system), and downstream tests should stay red until it lands; do not soften tests to go green.

### failures flip between runs
Intermittent ordering suggests a race or flake layered on top. Stabilize run ordering first, then triage.

Compatibility: dbt build and test with store_failures for failing row inspection; lineage from manifest.json depends_on. Applies to generic and singular tests on all adapters.

## Why it happens

Tests assert contracts on a model and on its relationships to other models. A single upstream defect violates many contracts at once: its own value tests, child relationships tests, and any consistency test downstream. The failure count therefore measures blast radius, not the number of bugs, and DAG order is what separates the one cause from its shadows.

## Edge cases / pitfalls

- Fixing symptom tests first (loosening them) destroys the signal and leaves the root defect shipping data.
- A renamed column can fail tests in two clusters that look independent; check recent schema changes before assuming two roots.
- Record the root versus symptom mapping in the incident note; the pattern speeds up the next triage.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gsr_Zy-DQfdxcU8-rZ0UvQ