## TL;DR

Following a deep ref chain by opening files one by one does not scale. The agent should ask dbt for the chain: `dbt ls --select +[TEST NAME] --output json` returns every ancestor, and the manifest's `child_map`/`parent_map` walk it programmatically. Then read only the failing node's SQL.

## Error

```text
agent failed to read the failing test's sql: ref chain too deep to follow
```

## Steps

1. Get the ancestor set: `dbt ls --select +[TEST NAME] --output json`. Expected: the full upstream list without manual walking.
2. Identify the failing node from the test output (the test name usually encodes the model). Expected: one node to focus on.
3. Read that node's SQL file only. Expected: the agent studies the actual failure site, not the whole chain.
4. If the failure involves an ancestor's logic, extract that ancestor's node from the manifest by ID with `jq`. Expected: targeted reads, one node at a time.
5. Fix the failing node and rerun the test. Expected: the test passes without chain-wide edits.

## When to use

- A failing test sits atop a deep ref chain.
- Manual chain-following is slow or confusing.

## When not to use

- The chain is shallow (a few files are fine to read directly).
- The test SQL itself is broken (fix it directly).

## Tool compatibility

- dbt Core 1.0 and later, all adapters. Graph operators are core features.

## Variant phrasings

### Test failure caused five models up the chain

The ancestor set from `dbt ls` shows exactly which five.

### Circular-looking chains

dbt graphs are DAGs; apparent cycles are usually diamond dependencies, which `dbt ls` handles fine.

## Why it happens

Deep chains defeat manual navigation: each hop needs a file open, a ref resolved, and context held. dbt already computed the graph; querying it is instant and exact.

## Edge cases

- Test node IDs differ from model node IDs; select the test name as reported in the failure.
- The manifest must be fresh; parse first if the chain looks wrong.
- Cache the ancestor JSON for the session; the chain does not change mid-fix.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Q-QHq2aae2gcgSqolyEHYA