suggesting-dbt-bouncer-checks

name	suggesting-dbt-bouncer-checks
description	Analyzes a dbt project and suggests dbt-bouncer checks that already pass (for existing projects) or a sensible starter config (for greenfield projects). Use when adding dbt-bouncer to a project, creating or extending a dbt-bouncer.yml config, or enforcing dbt conventions with dbt-bouncer.
user-invocable	true
metadata	{"author":"godatadriven"}

Suggest dbt-bouncer checks for a dbt project

dbt-bouncer enforces conventions in dbt projects by running checks against dbt artifacts (manifest.json, catalog.json, run_results.json). This skill helps you propose a dbt-bouncer.yml config tailored to a project.

Additional Resources

• Check catalog - Commonly suggested checks grouped by category
• Config reference - Config file structure and global options

Prerequisites

• dbt-bouncer installed (pip install dbt-bouncer).
• A manifest.json in the project's target/ directory. If missing, run dbt parse (fast, does not hit the warehouse).
• catalog.json is only needed for catalog_checks (requires dbt docs generate). Prefer manifest_checks when the catalog is unavailable.

Workflow: existing project (brownfield)

The golden rule: suggested checks must pass against the current project. Never suggest a config that breaks CI on day one.

1. Inspect the project. Read dbt_project.yml, the models/ directory layout, and a sample of model .yml property files. Identify:
   • Layer structure (e.g. staging/, intermediate/, marts/) and naming prefixes (stg_, int_).
   • Documentation habits (are descriptions populated? which layers?).
   • Testing habits (unique/not_null on marts? relationship tests?).
   • Source conventions (freshness, loader, file naming).
2. Codify what is already true. Suggest checks that formalize existing conventions, e.g. if all staging models start with stg_, suggest check_model_names with model_name_pattern: ^stg_ and include: ^models/staging.
3. Scope aggressively. Use include/exclude (regex on file path) to limit each check to where the convention actually holds.
4. Use severity: warn for aspirational checks. Checks the team wants but doesn't yet satisfy should be warnings, either per-check or globally at the top of the config.
5. Validate before proposing. Always run dbt-bouncer run against the drafted config and iterate until it exits 0 (warnings are acceptable, errors are not). Do not modify any model SQL or YAML to make a check pass — adjust the check's scope or severity instead.
6. Present the config with rationale. For each suggested check, state in one line which observed convention it codifies.

Workflow: new project (greenfield)

No existing conventions to respect, so suggest an opinionated baseline:

1. Start from the low-controversy checks in check-catalog.md: naming per layer, lineage rules between layers, check_model_has_properties_file, check_model_description_populated, check_model_has_unique_test, source freshness/loader checks.
2. Match the config to the project's planned layer structure (ask the user if unclear).
3. Set coverage checks (check_model_documentation_coverage, check_model_test_coverage) with achievable thresholds that can be ratcheted up later.
4. Recommend wiring dbt-bouncer into pre-commit and CI so conventions are enforced from the first model.

Guardrails

• Never edit models, sources, seeds, or property files to satisfy a check unless the user explicitly asks.
• Only suggest check names that exist in the installed dbt-bouncer version. Verify with the documentation or by running the drafted config — unknown check names fail config validation.
• Prefer manifest_checks over catalog_checks/run_results_checks unless the corresponding artifacts are freshly generated.
• One convention per check entry; the same check name can appear multiple times with different include scopes.