A Data Quality Review Stack for dbt Changes

dbt changes can look clean in a pull request and still break trust in the warehouse. The risky part is rarely one SQL file by itself. It is the combination of lineage, schema metadata, model parity, expectation coverage, and the review gate that decides whether generated analytics work is ready to merge.

In Short

A useful dbt review stack does four jobs. It maps what changed, checks whether documentation kept up, compares the proposed output against warehouse reality, and records validation results in a form a reviewer can inspect. That matters more when an agent drafts the SQL, because the reviewer needs evidence beyond “the model compiled.”

The official dbt documentation is the right baseline for project structure, model selection, manifests, tests, and docs. The Great Expectations documentation is the right source for expectation suites, validation results, checkpoints, and data docs. Use those sources for tool behavior. Use ASE skills to route the repetitive review work.

Who this is for

This workflow fits analytics engineers, data platform teams, and product analysts who let agents help with dbt models, refactors, migration work, or schema documentation. It is also useful for small teams where one person writes the model and another person needs a compact packet for review.

It is not a replacement for domain judgment. An agent can explain lineage and run checks, but it does not know whether a metric definition is politically or financially acceptable. Keep business-owner review for high-impact models, finance reporting, customer-facing metrics, and anything feeding automated decisions.

Starter workflow

Start with the pull request, not the warehouse. Ask the agent to identify changed dbt files, affected selectors, dependencies, exposures, and tests. The goal is a short list of impacted models and the reason each one is in scope. If the diff touches a staging model, the review packet should include downstream mart models and dashboards. If it touches a metric model, include owners and consumers.

Next, check schema metadata. Generated SQL often changes column shape faster than documentation changes. Ask for missing descriptions, stale inherited metadata, renamed columns, and source freshness assumptions. Do not accept a model review where the SQL and schema YAML tell different stories.

Then run parity checks. For refactors and migrations, compare old and new relations instead of relying on compile success. Keep row counts, null-rate changes, sample value diffs, and any tolerated deltas. A reviewer should be able to see whether a difference is expected, explained, and bounded.

Finally, turn assumptions into executable validation. Great Expectations-style checks are useful when the team can name the rule: accepted values, ranges, uniqueness, null thresholds, referential checks, or freshness. Put failed checks in the review packet with owner, severity, and next action. A failed expectation is not always a blocker, but an unexplained failed expectation should be.

Recommended ASE skills

Use dbt Model Lineage Analyzer first when the reviewer needs a graph of upstream and downstream impact from dbt artifacts. Pair it with dbt-osmosis schema YAML sync when metadata drift is the main risk.

For migration or refactor work, add dbt-audit-helper parity checks. It gives the review a concrete comparison between relations instead of a vague confidence statement. For explicit data quality rules, use Great Expectations Data Validation Pipeline so assumptions become repeatable checks.

Two supporting skills round out the stack. Altimate Code for deterministic SQL and dbt analysis is useful when agent-generated SQL needs dbt-aware static context. dbt-checkpoint pre-commit gates catches model hygiene and metadata issues before the review gets noisy.

What to watch

Watch for checks that prove the wrong thing. A passing dbt test can still miss a shifted metric definition. A row-count match can hide changed values. A clean lineage graph can still omit a dashboard or notebook that depends on a table outside dbt. The review packet should say what was checked and what was not checked.

Also watch permission boundaries. Agents reviewing dbt changes may need repo access, manifest artifacts, warehouse metadata, and sample query output. Keep credentials scoped, prefer read-only warehouse access for review, and avoid copying sensitive rows into the packet when aggregate evidence is enough.

FAQ

Should every dbt change get this full stack? No. Small documentation-only changes may only need schema review. Model refactors, source swaps, metric changes, and agent-written SQL deserve the fuller packet.

Is Great Expectations required if dbt tests already exist? Not always. dbt tests are often enough for model constraints. Great Expectations helps when you need richer validation suites, readable data docs, or checks shared across systems.

What should block a merge? Block on unexplained parity differences, stale or missing schema metadata for important columns, failed validation with no owner decision, or lineage impact that the reviewer cannot explain. Compile success alone is not a release gate.