## TL;DR

The agent renamed a model but missed a downstream ref, and the nightly run found it. Search the whole project for the old name, fix every stale ref, and compile the full project. Require full-project compile in the agent's done criteria for any rename.

## Error

```text
agent ref rename missed one downstream model: dag broke at 3am
```

## Steps

1. Find every stale reference: grep -rn "ref('old_name')" across the project, including macros and tests.
   Expected: You find the missed downstream model (and any others).

2. Update each stale ref to the new name.
   Expected: No references to the old name remain anywhere.

3. Run dbt compile on the full project, not just the renamed model.
   Expected: Full compile succeeds; the DAG is whole.

4. Run dbt ls to confirm the renamed model has all its downstream children attached.
   Expected: The DAG shows the complete downstream chain under the new name.

## When to use

- a ref rename broke the DAG because one downstream was missed
- nightly run fails on a ref to a model that no longer exists under that name
- an agent renamed a model and verified only the renamed file

## When not to use

- the rename was complete and verified (then something else broke)
- the missing ref is in a deleted model (that is cleanup, not a missed rename)
- the error is a different compile error

## Tool compatibility

- grep for ref('old_name') across the project
- dbt compile full project to catch stragglers
- dbt ls to visualize the repaired DAG

## Variant phrasings

### agent renamed a source instead of a model
Same hunt, but in sources.yml and source() calls. Missed source renames break the same way.

### rename missed a test's ref
Tests reference models too. The grep must cover the tests directory, not just models/.

## Why it happens

Agents verify the file they edited and maybe its direct children, but ref() calls live in tests, macros, and exposures too. A rename is a project-wide operation; verifying one file is how the 3am page happens.

## Edge cases

- Exposures and metrics reference models by name as well; include them in the rename checklist.
- Make full-project dbt compile a required agent done-criterion for any rename, no exceptions.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EbgxKF85wfzfWo49X9tLfQ