dbt-labs / dbt-labs/dbt-agent-skills

[New Skill] Data investigation workflow for the Data/Test Failure path in `troubleshooting-dbt-job-errors`

Open
#79 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
710
Forks
62
Avg merge
1d 18h
Merged PRs (30d)
5

Description

## Why don't the current skills work for your use case?

The `troubleshooting-dbt-job-errors` skill references a `discovering-data`
skill when it classifies an error as a Data/Test Failure. The flowchart
routes to:

> "Use discovering-data skill to investigate"

And later in the instructions:

> "Use the discovering-data skill to investigate the actual data."

The existing `references/discovering-data.md` covers data exploration and
investigation well, including data quality issues. What it doesn't
specifically cover is the layer-by-layer lineage tracing workflow — starting
from the source and comparing row counts/totals at each transformation
step to pinpoint where the numbers first diverge.

What seems to be missing is guidance for a different workflow: you already
have models built, a test just failed (or stakeholders reported wrong
numbers), and you need to trace the issue through existing lineage to find
where things went wrong. That's less about discovering what's in a table
and more about comparing expected vs actual values at each layer of the DAG.

## What is the use case for this new skill?

A dbt job runs successfully (no build errors), but the numbers in your mart
tables — row counts, totals, averages — don't match what's in the source.
Or a test fails and you need to understand why.

The agent would need to:

1. Walk the existing lineage using `dbt show` — check row counts/totals at
each layer (staging → intermediate → mart) to find where the numbers
first diverge from what's expected
2. Diagnose common root causes, such as:
- A join key changed or has new values the model doesn't handle
- Source data arrived late or is incomplete
- A join accidentally multiplies rows (e.g., 1 order has 3 payments →
3 rows instead of 1)
- NULLs silently dropping rows in joins or filters
- A WHERE clause was changed and is now excluding valid records

This feels different enough from the existing `discovering-data` reference
that it might need its own skill or reference, but I could also see it as
an extension. Happy to hear your thoughts on the best approach.

I work as a data engineer using dbt professionally and have dealt with
these kinds of investigations regularly. I'd love to contribute if you
can point me in the right direction.

## Would this benefit most dbt users?

Yes — "the dashboard numbers look wrong but nothing failed" is a very
common situation in analytics engineering. Any team with staging,
intermediate, and mart layers runs into this. Having guidance for the
agent to systematically trace the issue through existing lineage would
complement the current `discovering-data` reference (which covers
table-level exploration and profiling) and complete the data/test failure
path that `troubleshooting-dbt-job-errors` already outlines.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.