Skip to content

exmergo/dex / claude/skills/maintain

maintain

Verified

Use this to find out whether an existing dbt project or semantic layer (dbt, Ossie, SLayer or Cube) is correct against its warehouse, and if not, why. `maintain verify` checks the project as it stands; against a .dex/ snapshot, `maintain check` finds schema, volume, grain, and semantic drift and `maintain reconcile` proposes the fix. Reach for it whenever an existing project is suspected wrong, whether or not anything is known to have changed: "this model is wrong, work out why", "the numbers look too high", "some rows are missing", "this column is empty", "duplicates in my fact table", "the project is broken", "diagnose why this test fails", "a test fails and nobody changed the model", "which models have no tests", "how good is our test coverage", "did anything drift", "the metric definition changed". Read-only; fixes come back as reviewable diffs and never overwrite hand-written work. Writing the fix, or repairing a model you just edited, is transform's; a data question with no project is explore's.

FileKindSize
SKILL.mdskill md43.3 KB
evals/evals.jsonconfig9.4 KB
references/axes.mdmarkdown52.9 KB
scripts/run.pyscript31.8 KB

references/axes.md

View on GitHub
# Maintain axes: what each command detects, holds, and costs

Lookup detail for the maintain subcommands. What you must and must not do is in
`SKILL.md`; this file says what a finding means and where it comes from.

## The baseline: `maintain snapshot`

`maintain snapshot` pins the current `.dex/cache.json`, so the grain baseline is
the exact-distinct verdicts `explore map` already computed, plus per-layer
fingerprints of the dbt project and of the semantic layer.

- **The two project layers are fingerprinted independently.** The transform
  layer comes from the dbt project; the semantic layer comes from whichever vendor
  `semantic.vendor` names, which may be dbt's own or a native format such as
  Apache Ossie, SLayer or Cube. A repository with a semantic layer and no dbt project still gets
  a baseline and runs every free axis: `transform_layer` comes back null. The
  warning that no project was fingerprinted is reserved for the case where
  neither layer answered.
- A native semantic layer contributes its definitions per dataset and per
  metric, each with a content hash, the relation behind it, the column each field
  resolves to, its declared keys in the arity they were written, and its
  relationships with every ordered column pair. Whether that side was captured is
  itself recorded, so a baseline written before it reports the relationship axis
  as unchecked rather than clean.
- Each dbt model's **declaration** is fingerprinted per model and per column: the
  model's and each column's `description`, and every key under their
  `config.meta.dex` (grain, population, assumptions; a column's role, additivity,
  unit, aggregation, null rule, references). One hash per field, never the
  declared text, so a population filter's values do not land in `.dex/`. Hashes
  are taken over a canonical form: reflowing a description, reordering a grain or
  a filter's values, or moving the entry to another YAML file is not a change.
  `data.transform_layer.declared_model_count` says how many models were
  fingerprinted (`0` is a project that declares nothing, which is a baseline;
  `null` is a format that does not read declarations). A native dbt versioned
  model is fingerprinted per version, from the entry dbt builds each version
  from, under its label (`dim_teams.v2`), so drift names the version whose
  declaration moved.
- Without a cache it captures a metadata-only baseline and says so. It warns
  when the cache it pinned is thin (objects without column detail) or older than
  the profile freshness window, because either makes "accept current state" only
  partly true.
- Past 50 objects, `explore map` profiles the top 25 by rank and enters the rest
  as metadata alone. The snapshot envelope reports `column_detail_count` against
  `dataset_count` plus a warning naming what it could not cover.
- The baseline records the engine release that wrote it (`tool_version`). Every
  axis that reads it warns when that release is not the running one, because
  drift measured across an engine change can reflect the engine as well as the
  warehouse. Re-running `maintain snapshot` re-pins it at the running release.
- `--project-only` refreshes the transform and semantic fingerprints without
  opening the warehouse, carrying the existing `warehouse` block,
  `warehouse_from`, and `cache_updated_at` forward. It requires an existing
  snapshot and refuses connection-target flags (`--connector`, `--path`,
  `--scope`, `--project`, `--dataset`).

## `maintain check`

Sweeps every axis against the snapshot and returns one report ranked by blast
radius. Read-only. `check` warns when the baseline looks stale.

## `maintain schema [<objects>]`: structural drift

Source columns and tables added, dropped, retyped, or renamed; nullability
changes; declared sources the warehouse no longer honors; a model added,
removed, or content-changed since the baseline. Free.

Under `semantic.vendor: slayer` the SLayer models are also held to the warehouse
by SLayer's own `validate-models` rules, run on the metadata Dex captured and
never through a SLayer datasource: `declared_column_missing`,
`declared_type_conflict` (SLayer's type buckets: number, string, boolean,
temporal, and a list; a column that became a list is `remedy_kind: reingest`
with the warehouse's `element_type`, and reconcile states it as a `type: ARRAY`
declaration rather than `slayer ingest`), `declared_relation_missing` (a table gone since the baseline), and
`declared_dependency_dropped` (a join, measure or filter lost to another drop).
Each carries the model's whole removal under `data.removal`, which is what
`maintain reconcile` plans.

Under `semantic.vendor: cube` the same four codes hold the cubes and views to
the warehouse by Dex's own rules (Cube compares a model only inside a Cube
server, which Dex never starts): a member whose `sql`, filter or segment reads a
column the table no longer has, a `time` dimension on a column that is not
temporal or a `number` dimension or summing measure on text, a cube's table gone
since the baseline, and a member, join or view include lost to another drop.
Each carries its cube's or view's removal under `data.removal`.

## `maintain volume [<objects>]`: freshness drift

Row counts that collapsed, spiked, or went to zero: the "is the data still
flowing?" axis, distinct from "did the shape change?". Free metadata. An object
the warehouse keeps no count for (a view anywhere, an external table on
BigQuery) is named in `warnings` as not compared.

## `maintain grain [<objects>]`: grain drift

A key that now has duplicates, a changed row-per-entity cardinality, or an
increased join fanout. It also re-verifies the grains the repository
*declares*: a dbt model-level `unique_combination_of_columns`, and a semantic
layer's own key declarations. A multi-column declaration is measured as one
complete composite, never one column at a time. Aggregates only.

- A native semantic layer's keys reach this axis and nothing else reaches them,
  since such a layer is never the transformation project. They take the
  identical billed handshake on a metered warehouse.
- The composites it re-probes are the ranked, artifact-suppressed set
  `explore profile` reported.
- Below `maintain.grain_min_rows` rows (default 100), a uniqueness-regression
  finding is damped to `low`, and the damping is named in the finding's `data`
  (`severity_floor_applied`, `grain_min_rows`).
- A single-column key that is not the grain, and is still unique together with
  a column the baseline read as constant, reads `medium`: the rows were added
  along that column (a second tenant, region or repository), and
  `data.still_unique_as` names the combination. A real duplicate repeats that
  combination too, so it stays `high`, and a lost grain always does. The same
  finding says whether the dataset's grain still holds (`data.grain_holds`),
  from the count the axis already takes; that alone never lowers the severity,
  because a surrogate grain stays unique through a real duplicate.
- Finding codes: `key_lost_uniqueness` (proven unique at baseline, not now),
  `declared_grain_not_unique` (declared, never held),
  `join_orphans_increased` (a baseline join's orphan fraction rose),
  `declared_join_orphans` (a join declared now, at 20% orphaned or more,
  `high` from 50%, that the baseline never measured or measured at or above
  that bound already; `data.baseline` is `absent`, `unmeasured` or
  `measured`; the joins come from the project and from a native semantic
  layer, not from a dbt layer's entities), and
  `join_cardinality_exceeded` (a join whose declared arity, SLayer's
  `cardinality` or Cube's `relationship`, does not hold: the side it says is
  unique is not).
- A join that declares no cardinality is named in `warnings` as unchecked.
- A key or join whose table nothing counted (no free row count, and a scan
  that does not count, as on Databricks) is named in `warnings` as not
  verified, never passed. Where the scan counts (Postgres, Trino), the check
  runs without a free count.

## `maintain semantic [<objects>]`: definition drift

Definitions changed, added, or removed against the baseline; a source relation
that is gone; a dimension, entity, measure, or declared key naming a column that
is gone; a relationship whose endpoint or column pairs no longer resolve, which
is `high` because a join nothing can resolve is a broken layer; and categorical
dimensions whose set of values widened or narrowed underneath their metrics.

The cardinality half needs a semantic model that names a table, through a
transformation model (dbt) or directly (SLayer's `sql_table`, a Cube's
`sql_table`), and categorical dimensions recorded against it. Ossie records
none, so on an Ossie layer this command is free and offers no scan.

**Declaration drift** is the third free focus of this axis. A declaration
records what a model means, so changing it changes what the model's numbers
mean with the SQL untouched, which the schema axis's `model_changed` cannot see.
Each finding names the model (`identifier`, `data.model`), the column where it
is one, and the field:

- `declaration_changed`: one field of a declaration present on both sides was
  changed, newly set, or cleared (`data.field`, `data.change` of `changed`,
  `added` or `removed`). A changed population, grain, additivity, unit or
  aggregation is `high`; a role, references, null rule, assumptions, or a
  `meta.dex` key Dex does not define is `medium`; a description is `low`. A
  cleared field ranks one step lower, capped at `medium`, and a newly set one is
  `low`.
- `declaration_added` / `declaration_removed`: a model or a column that declares
  something now and declared nothing at the baseline, or the reverse, with the
  fields under `data.fields`. A model whose whole declaration is gone is one
  finding listing its columns, and `data.model_present: false` says the model
  itself was removed too.

Each one names under `impacted_metrics` the metrics over a semantic model built
on that model. `data.declaration_drift` says whether this focus ran:
`{"checked": true, "baseline_declared_models", "declared_models"}`, or
`{"checked": false, "reason"}` with a warning. A baseline pinned before
declarations were fingerprinted is unchecked, never clean and never every
declaration newly added. So is a versioned model on a baseline that keyed its
declaration by the bare name, before declarations were read per version: it is
named under `data.declaration_drift.unchecked_models`, with
`unchecked_reason: baseline_predates_versions` and a warning, and is never
reported as removed. `maintain snapshot --project-only` baselines them without
re-measuring the warehouse, which is also how an intended declaration
change is accepted. `maintain reconcile` answers these findings with advisories
only: a declaration is a human's decision, so Dex never rewrites one to match the
baseline.

A native semantic layer (Ossie, SLayer, Cube) is compared the same way, from
each definition's own declaration: every key of the `dex` block in its
`ai_context` (Ossie) or `meta` (SLayer, Cube) and in each member's, a member's
fields keyed by the column it reads, and its primary key as the `grain`, so a
changed primary key is a `high` grain change and a `grain` written in the `dex`
block is not read. The finding names the definition (`commerce.orders`, a SLayer
model, a cube) and carries `data.layer: semantic` and `data.vendor`. With no
transformation project, `data.declaration_drift` is the layer's own status, with
its `vendor`; beside a dbt project the layer's status rides under
`data.declaration_drift.semantic_layer`, and `checked` is true only when both
were compared. A baseline pinned before native declarations were fingerprinted,
a layer whose declarations could not be read, and a change of vendor are
`checked: false` with a `reason`, never clean; `maintain snapshot
--project-only` baselines them.

The baseline records which vendor read the layer, and for SLayer the release and
model format version. A change in any of them is reported first
(`semantic_vendor_changed`, `semantic_format_changed`), and definitions are not
compared by content across it, because an upgrade changes every hash without a
definition changing.

## `maintain verify [<selector>]`: is the project right now

Needs no baseline. The classes of finding:

- **Build status**: nodes that failed; nodes skipped because a parent failed
  (naming the one that actually failed, through a chain of skipped parents);
  nodes that warned rather than failed (`node_warned`, ranked low, because a
  project running relationship tests at `severity: warn` has warnings by design);
  and models the project declares that built no relation.
- **Row population**: `row_loss` where a model holds materially fewer rows than
  its **driving parent** (the relation in its FROM clause, followed through the
  CTE chain, as distinct from anything it joins) and nothing in its SQL accounts
  for the shortfall; `row_fanout` where it holds materially more. Each names
  every join beside its own key and states both counts. A fan-out on a model
  whose declared grain (a declaration, a `unique` or
  `unique_combination_of_columns` test, or a primary entity, never the naming
  guess) the same run proved unique is capped at `low`, with
  `data.grain_proven`: the extra rows are the grain the model declares (anchors
  times windows, a date spine times entities), not duplicates. A fan-out
  through joins whose key Dex cannot read (a range or inequality join) is
  capped at `medium`, with `data.join_key_read: false`. Both caps name
  themselves in `data.severity_cap_applied`, and the finding stays listed. A
  model with a `WHERE`, `GROUP BY`,
  `DISTINCT`, `QUALIFY`, `LIMIT`, a semi or anti join, or a set operation is never
  reported for loss, and an incremental model is skipped outright (on
  `transform build --full-refresh --verify`, only one the build did not rebuild,
  or a microbatch model). A model that
  generates its rows in SQL, such as `range(...)` or a `VALUES` clause, has no
  parent relation. That is named in `notes`. A model whose driving parent is
  the project's time spine (a `time_spine:` config, or the
  `metricflow_time_spine` name) or a model generated in SQL
  (`dbt_utils.date_spine` included) is not compared either, since the spine
  supplies anchors rather than a population, and `notes` names it (#988). A
  model that only joins a spine keeps its check. A real parent relation that is
  absent from the warehouse is still a warning.
- **Column contract**: `column_missing`, `column_undeclared` and
  `column_type_mismatch`, the built relation's columns against `schema.yml`.
- **Grain**: `grain_broken`, from one source per model, in this order: the
  grain the model's declaration states (`config.meta.dex.grain`, so a
  composite grain is checked with no `dbt_utils` test), a `unique` test, a
  `unique_combination_of_columns` test, a semantic model's primary entity,
  then a naming guess. `data.source` says which one. A declared grain is
  counted in the declared-fact statement below, so it is priced with it.
  `data.grain_coverage` (#1223) holds one record per declared key, whichever
  source declared it (`model`, `columns`, `source`, `status`, `reason`,
  `measured`), so a key that held is stated rather than read out of an absent
  finding. `status` is `proven` (the exact distinct count reached the row
  count), `broken` (beside its `grain_broken` finding), `not_applicable`
  (`empty_relation`), `unchecked` or `not_planned` (`priority`: a key from a
  lower-ranked source the model's checked keys displaced; one on the same
  columns as a checked key is judged by it and gets no record of its own).
  `unchecked` names its `reason`: `no_relation`, `ambiguous`,
  `metadata_unreadable`, `missing_columns`, `scan` (the connector could not
  run the count), `scan_offered`, `no_count`, `refused` or `not_measured`. The
  naming guess has no record, and the field is absent when the grain class is
  suppressed. Only `proven` is a pass. `measured` carries the row and distinct
  counts where both were read; the warehouse's own words stay in `notes`.
- **Join contract** (#228, #857): every equality join's coverage, measured
  with one aggregate probe per driving relation and recorded under
  `data.join_coverage`, one record per join:
  - `declared`: what the declaration says about the join. It is `required` when
    a column it supplies is declared `null_rule: never` on a LEFT join, or the
    column carrying the driving key declares a `references` that names the
    joined relation, whatever its `role` and on a LEFT join too (#1459): a
    `references` means every non-null value exists in the parent, which is how
    the `relationships` test it renders reads it, so a missing reference is
    written as a NULL and passes both. A version label
    (`dim_teams.v2.team_id`) names that version's relation, and a bare name
    the version an unversioned `ref()` resolves to. `optional` is set when every column it supplies
    states a NULL rule other than `never`. NULL keys are `excluded`, or
    counted `unmatched` where the key's column is `null_rule: never`.
  - `measured` and `coverage`: eligible, matched and unmatched rows and
    distinct keys, NULL-key rows apart. Coverage is `null` when nothing is
    eligible.
  - `key_conversion` (#861), on a join that compares a key through a cast or a
    `lower`, `upper` or `trim` (`try_cast(a.k as int) = b.k`): each side's keys
    as the probe applied them, a hard cast measured as its safe form. Keys the
    conversion fails on stay eligible and unmatched, and are counted apart as
    `measured.conversion_failed_rows` and `conversion_failed_keys`, so a failed
    cast reads differently from a missing parent.
  - `effective_input` (#1085, #1324), on a join one of whose sides is read
    through a filtering or grouped CTE or subquery: per side, the physical
    `relation`, the scopes it was read `through` and the `filters` the probe
    applied to it. The measured counts are over those rows, so a key present
    only in rows the filter drops is not a match. Carried only when every
    filtering hop reads one relation, its only reducing clause is a `WHERE`,
    and each conjunct is a row-by-row condition over columns and literals
    (comparisons, `IN` over a literal list, `BETWEEN`, `LIKE`, `IS`, boolean
    logic, `coalesce`, casts and `lower`/`upper`/`trim`, as in
    `where coalesce(_fivetran_active, true)`) that traces to the key's own
    physical relation. A side grouped by *exactly* the join's key columns
    (a direct `GROUP BY` over one input, with no `HAVING`, window, `LIMIT`,
    set operation or grouping modifier (`ROLLUP`, `CUBE`, `GROUPING SETS`,
    `GROUP BY ALL`), and optionally the supported `WHERE`) also carries
    `grouped_by`, the key columns it groups by. That side is probed over its
    groups, never the ungrouped relation underneath, and its own denominator
    is `measured.group_rows`. Its aggregate outputs are attributed through the
    model's final projections, so `null_rule: never` on a renamed output
    (`o.total_amount as spend`) still makes the join required, and an
    aggregate the model does not project is not treated as supplied. A grouping by anything else (an extra column, a
    subset of a composite key, an expression, or a grouping inside another
    grouping) stays `filtered_cte`.
  - `status`: `satisfied`, `contradicted` (with the finding), `not_applicable`
    (an empty input or all-NULL keys: no coverage, which is not full coverage)
    or `unchecked`, with a `reason_code`: `non_equality_join`,
    `unsupported_key_expression` (a key rewritten by a function other than a
    cast, `lower`, `upper` or `trim`), `no_safe_cast_on_connector` (a cast key
    on Postgres, which has no cast that returns NULL, to a type other than
    `smallint`, `integer` or `bigint`: those are measured through a guarded cast), `key_and_filter_condition`, `ambiguous_using`, `unresolved_column`,
    `set_operation_cte` (a column read through a UNION CTE, which is not a
    warehouse table), `filtered_cte` (a reducing scope of any other shape: a
    `GROUP BY` other than exactly the join's key columns, `DISTINCT`, `LIMIT`,
    `HAVING`, `QUALIFY`, a join beside the
    filter, a subquery or clock function in it, or a filter on a computed or
    window column such as `rn = 1`, or a join that can drop rows of the
    relation the key is read from: an inner, bare, comma or CROSS join, a
    RIGHT join with the key on its left, or a LEFT join with the key on its
    joined side; the reason names the scope and the shape),
    `unparseable_sql`, `relation_not_found`,
    `probe_refused` or `scan_offered`.

  Findings:
  - `join_no_match` (high): a nonempty eligible population matched nothing.
    No threshold. `low` when every column the join supplies is declared as
    allowed to be NULL.
  - `join_orphans` and `join_zero_overlap`: on a required join any unmatched
    row (`threshold_source: contract`, high). Otherwise the stated defaults,
    0.2 and 0.9 of eligible rows (`threshold_source: default`). On a LEFT join
    with no requirement (no `references` on its driving key), unmatched rows are the optional relationship the join
    writes: no `join_orphans`, and `join_zero_overlap` at medium. On an INNER
    join with no requirement whose unmatched rows the declaration accounts for
    (an `assumptions` entry whose `column` names the driving key column, or a
    `population.filters` entry on it), the join is the model's filter: the
    record is `satisfied`, keeps its measured counts, and names the entry
    under `unmatched_accounted_for` (`by`: `assumption` or
    `population_filter`, the `column`, and the `withheld_finding` the default
    would have raised). `join_no_match` still stands (#1162).
  - `join_field_all_null` (high): a column the join supplies, declared
    `null_rule: never`, NULL on every row. `join_field_newly_null` (medium):
    one with no rule, NULL on every row, where the exploration cache profiled
    the same relation with values in it. Otherwise the column is listed on the
    record as `derived_columns_all_null`, not reported.
- **Declared facts** (#496), each an aggregate-only statement against the
  built relation:
  - `unit_out_of_range` (medium): a column declared `fraction` with values
    outside 0 to 1, or declared `percent` whose values all sit within 0 to 1.
    States the observed `min` and `max`; the second case is a question, not
    proof, since genuinely small percentages land there too.
  - `additivity_contradicted` (medium): a column declared `additive` that the
    cumulative detector reads as a running total. The probe orders by the
    declaration's own entity and time columns (a composite grain, or the
    `foreign_key` and `time` roles).
  - `population_contradicted` (high): a value a `population.filters` entry
    excludes still present (for `includes`, any other value or NULL), as a
    count and never as rows.
  - `parent_population_missing` (high) and `parent_population_unexpected`
    (high), for a model declaring `population.parent` (#857): eligible parent
    keys with no row in the model, and model keys the parent does not have,
    as distinct-key counts. A population filter whose column the parent also
    has is applied to the parent first (`excluded_by_filters`); one it lacks is
    named in `filters_unapplied` and drops the missing finding to medium.
    Unexpected keys are never the population. Each declared parent has a
    record under `data.parent_population` with the same statuses as a join.
    The parent may be an installed package's model (#1155), measured on the
    relation the manifest names for it; with `--target dev` (and on a build's
    `--verify`) a package that sets `+schema` is read in the
    `<dev schema>_<name>` namespace dbt built it into.
  - `population_delta` (high with orphan keys, medium with missing parents,
    low for parents kept with no children), on `transform build --verify`
    only, for a built model that declares no `population.parent` (#1228): the
    same counts against the parent dex drafts for it, plus the rows whose child
    columns are all NULL or zero (a sign of parents kept with no children, not
    proof: children whose amounts sum to zero read the same). It asks which rows the model is for rather
    than calling any of them wrong. Its records are under
    `data.verification.population_delta` (`satisfied`, `needs_decision`,
    `settled`, `not_applicable`, `unchecked`), and it is never named in
    `suppressed`. Not every such model gets one: with `--for-plan` only the
    plan's models are drafted (one the draft cannot reach is `unchecked`),
    without it at most 25, and a model nothing could be drafted for is named in
    `notes`, so an absent record does not mean the model was checked.
    `maintain verify` measures declared parents only.
  - `temporal_transition_count_mismatch`, `temporal_latest_transition_mismatch`
    and `temporal_first_attainment_mismatch` (high), `temporal_population_missing`
    and `temporal_population_unexpected` (high), and
    `temporal_provenance_contradicted` (medium), for a model declaring `history`
    (#1027): its columns against what the snapshot's versions and the declared
    policy give, as entity counts. Each contract has a record under
    `data.temporal_contracts`, keeping the snapshot's execution, the assertions
    checked, and what stayed unchecked apart. `no_history_observed` and every
    `unchecked` reason are not clean: see the transform skill's `declarations.md`,
    "Temporal contracts".

  `null_rule: never` is not checked here: it renders as a `not_null` test.
  `data.suppressed` names `unit`, `additivity`, `population`,
  `parent_population` and `temporal` whenever one
  did not run: nothing declares it, the relation is empty, the column is all
  NULL or aggregated away, too few observations to call, or the scan is
  offered.
- **Declared foreign keys, on a project format with no dbt artifacts**
  (#1197). dbt runs a `relationships` test itself and build status reads its
  result, so on dbt this does not run. Any other project format (one named
  under `project.format`) has each declared foreign key measured against its
  parent with the join contract's coverage probe, priced in the same single
  offer, and one record per key under `data.foreign_key_coverage`:
  - `model`, `column`, `to_model`, `to_column` and `source`, as the format
    declared the key, so two keys to the same parent stay apart.
  - `relation` and `to_relation`: where the format places each side, through
    `model_relations` (a source parent through `source_relations`). A model the
    format places nowhere is never looked up by name, since a same-named table
    elsewhere is not the relation it declared.
  - `measured` and `coverage` as on a join, with `null_keys: excluded`: a NULL
    child value is not constrained, as in dbt, and is counted apart.
  - `status`: `satisfied`, `contradicted` (with the finding), `not_applicable`
    (`empty_input`, `all_keys_null`) or `unchecked` with a `reason_code`:
    `no_declared_relation`, `relation_not_found`, `metadata_unreadable`,
    `column_not_found`, `probe_refused` or `scan_offered`. None of these is
    clean.

  `foreign_key_orphans` (high): any non-NULL child value the parent lacks
  (`threshold_source: contract`, threshold 0), stated as row and distinct-value
  counts. `data.suppressed` names `foreign_key_contract` when no key ran: the
  format declares none (in scope), declares nothing readable, or the warehouse
  is unreachable.

A project that does not compile is reported first and suppresses everything
else. `data.suppressed` names every class that did not run and why.

## `maintain coverage [<selector>] [--mutate]`: where the tests are

Needs no baseline and costs nothing: it reads a fresh `dbt parse` of a
throwaway copy of the project and opens no connection. It reports, it never
gates: `status` is `ok` whatever the coverage. `--mutate` is the one exception:
it refreshes stale and missing mutation scores, and that runs dbt (see below).

- **Sections.** `models`, `sources`, `snapshots` and `seeds` hold the root
  project's enabled resources. An ephemeral model is counted and marked
  `ephemeral`: dbt inlines it into its own tests and the models that read it.
  Package and disabled resources are in no denominator; `excluded` counts and
  names them with the reason, and counts disabled tests and tests on an excluded
  resource.
- **Own tests.** `own_tests` counts `generic` (attached to the resource),
  `singular` (a test file that reads it), `unit` (a unit test on that model) and
  `freshness` (a source's declared check) apart, and `severity` splits its data
  tests into `error` and `warn`. `tested` is true when any own test exists.
- **Downstream.** `downstream_tests.count` is the data tests on the resources
  that read this one, and `on` names those resources. They never count as its
  own coverage. A unit test on a downstream model is not one: it reads fixtures.
- **Incremental.** `incremental.incremental_branch_tests` names the unit tests
  that override `is_incremental` to true. Empty means no test runs the next
  incremental run, whatever the full build's tests say.
- **Columns.** `documented` is what `schema.yml` documents, `asserted` the
  documented columns a generic test is attached to, `unasserted` the gaps, and
  `undocumented_tested` the tested columns `schema.yml` does not document, which
  count nowhere. A column a singular test only reads is not asserted; it is
  `referenced` (below).
- **Referenced.** `columns.referenced_columns` lists each column a singular test
  reads, with the `roles` it is read in (`predicate` for WHERE, HAVING, QUALIFY
  and CASE conditions, `join`, `aggregation`, `grouping`, `projection`), the
  `tests` that read it, and whether it is `documented` and `asserted`. Columns
  only a singular test reads sort first. `columns.referenced` counts the
  documented ones, `columns.referenced_only` those no generic test asserts, and
  `summary.<section>.columns_referenced_only` is that count as its own ratio,
  never added to `columns_asserted`. Judge by role: a `join` read asserts
  nothing about the key, while a `predicate` read usually does. A singular test
  is rendered statically (`ref()`, `source()`, a `var()` with a literal
  default). One that other Jinja generates is read from the newest compiled
  manifest on disk, but only where that manifest holds the test with the same
  checksum. `data.singular_tests` counts the tests read (`resolved`, `partial`,
  `unresolved`), says where each was `read_from`, and names every test read in
  part or not at all with a `reason_code`: `macro_generated`, `jinja_block`,
  `unparseable`, `ambiguous_relation`, `unknown_relation`, `untraced_columns`
  (an unqualified column in a select over several relations, which needs a
  catalog this command does not read), `reads_no_column` or `no_sql`. Such a
  test is never read as reading nothing. Names and counts only: no SQL,
  expression or literal.
- **Summary.** `data.summary` leads the payload. Every ratio is
  `{numerator, denominator, of}`, and `of` names the denominator. Presence, unit
  tests, downstream-only protection, incremental branches and asserted columns
  are separate ratios; there is no blended coverage percentage.

A generic test is named by the test it applies (`not_null`,
`dbt_utils.unique_combination_of_columns`) and its column, never by its node
name: dbt names an `accepted_values` test after the values it accepts.

Lists are capped (25 resources per section with untested ones first, 12 tests
and 12 column names per resource, 10 downstream names, 25 excluded resources),
each cut counted in `data.elided` and named in `notes`; `--full` lifts them. The
summary always counts everything. A project that does not parse is reported
first and suppresses the inventory. Where dbt cannot parse at all (dbt or
`profiles.yml` missing, a declared package not installed), the newest manifest
on disk is read, `data.manifest.source` is `artifact` with its `generated_at`,
and a warning says tests changed since then are not reflected.

### Three more answers, each on its own

Presence, last-run status, mutation strength and declaration coverage are
separate questions. Report each with its own denominator; never fold them into
one coverage number.

- **Last run.** Each test carries `last_run`: `pass`, `fail`, `warn`, `error`,
  `skipped`, or `not_run` when the latest run did not include it. `not_run` is
  never a pass. `data.last_run` names the one run read (the newest
  `run_results.json` a `dbt build`, `test` or `run` wrote, from Dex's artifact
  directory or the project's target path) with its `generated_at` and
  `age_seconds`. Quote the age with the status: a status describes that run, not
  the project now. With no run results every test is `not_run` and a note says
  so; results from an invocation no dbt log names are not attributed. A source's
  freshness check reports no `last_run`: `dbt source freshness` writes its own
  artifact.
- **Strength.** A model carries `strength`, the score its last
  `transform test --mutate` recorded. `fresh` means the model's SQL as written and its own tests
  are what the run measured, and every downstream test it ran still reads the
  same. `stale` lists what `changed` (`model_sql`, `own_tests`,
  `downstream_tests`); its score is shown with its age and is not current.
  `missing` has no record, and `untestable` has no test, own or downstream, so
  `--mutate` would refuse it. `score` (the model's own tests) and
  `score_with_downstream` stay apart, and `complete: false` marks a run the
  budget stopped. `summary.models.strength` counts each status and bands the
  fresh scores; there is no project mutation score. A score counts only the
  defects Dex plants. The digest reads the SQL as written: a change in a macro
  the model calls, a parent's SQL, or a materialization set in
  `dbt_project.yml` does not stale it, so refresh after such a change
  yourself. Refresh one with `dex transform test --mutate <model>`, or every
  stale and missing one with `--mutate` (below). `untestable` with a `reason`
  (`no_mutable_sql`) is a model a run refused for its SQL alone: no comparison,
  filter, join, CASE, division, window frame or aggregate to plant a defect in.
  It reads `missing` again once its SQL or tests change.
- **Refresh (`--mutate`).** Runs `transform test --mutate` for each `stale` and
  `missing` model, then reports the sections as they now stand. Models run in
  the order the selector names them; with no selector, `missing` before
  `stale`, upstream before downstream, then by name. At most 25 run per call:
  `--max-models` narrows that and is refused above 25. `refresh.elided` names
  the rest, and running the command again continues with them.
  - On a metered connector every model is planned and priced first for free,
    and the batch is confirmed once (`needs_confirmation` with a line per
    model). Each run then draws on what the confirmed budget has left. A model
    the budget stopped part way is `complete: false`, and every model after it
    is under `refresh.not_run` with `reason_code: budget`. Free on DuckDB. Dev
    target only (`--target`).
  - `refresh.skipped` lists models a run would refuse, read off the manifest at
    no cost and not counted toward the cap: Python models, models with a
    `sql_header`, versioned models, whose versions share the name
    `transform test --mutate` takes, and, on a metered connector, a model only
    downstream tests read (`downstream_only`), since routing a mutant through
    them is opt-in there (`transform test --mutate <model> --downstream`).
  - A model whose tests pass no baseline is recorded too: it reads `missing`
    with `last_refusal`, and a refresh retries it after the models it has not
    tried yet, so it never holds the first slots. It never replaces a score
    that still describes the model.
  - `refresh.refused` lists the runs that refused, with a `reason_code` and the
    reason.
  - `refresh.refreshed` lists the models measured, with what each `was`, its
    scores, and whether it was `recorded`.
  - Refused in values-free mode, since `transform test --mutate` is not
    reviewed for it.
- **Declarations.** `data.declarations.facts` holds one record per declared fact
  on the selected models: `fact` (`grain`, `key`, `foreign_key`, `references`,
  `null_rule`, `population_filter`, `population_parent`, `population_rule`,
  `unit`, `additivity`, `history`), `column`, and `checked_by`: `dbt_test` (the
  generic `tests` that assert it run on every `dbt build`), `dex_verify` (the
  `verify` finding codes that can judge it on `maintain verify` or
  `transform build --verify`; that verify *can* judge it, not that it ran), `both`, `none`,
  or `prose` for a population stated only as a rule, which nothing can run.
  Unchecked facts come first. `summary.facts.checked` leaves prose out of its
  denominator, and `models_undeclared` counts models with no declaration apart
  rather than as zero coverage. A `references` counts as `dex_verify` only where
  the model reads the referenced model, since verify judges it through a join
  the model's SQL writes. Every record names its `source`, `dbt` or the vendor.
  A native semantic layer's keys and joins come from the fingerprint `maintain
  grain` re-verifies: a key names `declared_grain_not_unique`, a join
  `declared_join_orphans`, plus `join_cardinality_exceeded` where it is declared
  `many_to_one` or `one_to_one`, and a `many_to_many` join neither. What its
  `dex` metadata states reads `none`. A fact a dbt model and the layer both
  declare on one relation, spelled alike (a quoted part keeps its case, so
  `DB.SCHEMA.ORDERS` and `"DB"."SCHEMA"."ORDERS"` are two), is listed per source
  with `also_declared_by` and counted once.

## `maintain reconcile [<class>]`

Proposes the dbt edits that bring the project back in sync, as reviewable diffs,
optionally scoped to `schema`, `volume`, `grain`, or `semantic`. It composes every
layer's declarations first, so a grain the semantic layer already declares is not
proposed as though nothing declared it.

- `mechanical`: on a dex-scaffolded staging model it edits each drifted column
  into the model and nothing else: one projection added to or removed from the
  list the model names its columns in, and one entry in whichever YAML file
  already declares the model (a shared `models/schema.yml` included; Dex never
  writes a second declaration beside it, and never invents a test). The model is
  never regenerated, so a hand-written cast, rename or filter survives. On a
  project format that places a declaration but authors no staging model, it
  edits the drifted columns into that declaration.
- A dropped column the model's own logic still reads (`status as order_status`,
  `md5(status)`, a `where` on it) is advisory and names the use, since what that
  logic becomes is a decision. A model downstream that still reads the dropped
  column is named in `warnings`. Drift the project already reflects (an applied
  plan added the column) is advisory and stores no plan: re-run
  `maintain snapshot` to baseline it.
- `advisory`: the decision surfaced, at most backed by a test edit. It declines
  that test where the test would be wrong: if a model declares a composite grain
  covering the column, no column-level `unique` is proposed on it, and the warning
  names the combination.
- Type changes: nothing Dex writes declares a type, and the type it holds is the
  connector's own spelling (Snowflake reports `NUMBER(38,0)` and `NUMBER(10,2)`
  both as `FIXED`), so the proposal names both spellings.

## Cube layers (`semantic.vendor: cube`)

Every axis runs on a Cube layer, beside a dbt project or with none, and none
starts a Cube server or Node: each reads the configured model files and the
metadata Dex captured through its own connection. The wrapper installs the
`[cube]` extra for every `maintain` command where the vendor is `cube`.

| Axis | On Cube |
|---|---|
| `snapshot` | fingerprints each cube and view, each measure (as `cube.member`), each primary key (a composite one whole), and each join with its ordered pairs and arity; records `vendor: cube` and the validator release. Each compiled-only definition is recorded by its content (`opaque_definitions`) |
| `schema` | adds the four `declared_*` codes on Dex's metadata: `declared_relation_missing` (a cube's table gone since the baseline), `declared_column_missing` (a member whose `sql`, filter or segment reads a column the table no longer has), `declared_type_conflict` (a `time` dimension on a column that is not temporal, a `number` dimension or a summing measure on text), and `declared_dependency_dropped` (a member, join or view include that reads something that goes). A table neither the connection nor the baseline lists is a note, not a finding, and an expression Dex cannot read is named in `warnings` as unchecked |
| `volume` | unchanged: it reads the warehouse, not the layer |
| `grain` | measures every `primary_key` (a composite one whole) and every join's `relationship` (`join_cardinality_exceeded`; a `one_to_many` join is checked on its one side). Cube requires a `relationship`, so a join without one does not load; a join whose `sql` is not an equality of columns is named in `warnings` as unverified |
| `semantic` | definition drift free as everywhere, with `definition_changed` on a cube naming its table; a compiled-only definition whose content changed is `compiled_only_changed`; the dimension-cardinality half re-counts every non-time dimension that is one column (offered as a scan on a billed connector) |
| `reconcile` | stores the `declared_*` removals as a second plan, `data.semantic_plan_id`, through `semantic cube update`, cutting only the entries that go. A cube whose table is gone is never removed, and a view source whose join path walks a removed join, and the join it walks, stay advisory |
| `verify` | checks the dbt project only; Cube's keys and joins are measured by `grain`, not here |

A compiled-only file or element (JS, Jinja, `extends`) is compared by its content
alone, never structurally: a change is reported as `compiled_only_changed`, what
changed is not read, and the warning saying so rides every `maintain semantic`
and `maintain check` while the layer holds one, so the layer never reads clean.

A measure whose `filters` read a dropped column goes with the column rather than
losing its filter, because a filter removed quietly changes what the number
counts.

## Databricks Metric View layers (`semantic.vendor: databricks`)

Every layer-neutral axis runs on a Metric View layer, beside a dbt project or with
none, without a workspace connection to read it: each reads the configured files
and the metadata Dex captured through its own connection. The wrapper installs the
`[metric-views]` extra for every `maintain` command where the vendor is
`databricks`.

| Axis | On Metric Views |
|---|---|
| `snapshot` | fingerprints each view, each joined table that is not another view's source (`view.join.path`, with the fields that read it and its `rely` key), each measure (as `view.measure`), and each join with its ordered pairs, oriented child to parent; records `vendor: databricks`, the ported converter commit and `format_version: 1.1`, and each file's declared `version` under `definition_versions` |
| `schema` | adds the four `declared_*` codes, each naming the view, the element (`dimensions['region']`, `measures['revenue']`, `joins['customer.nation']`, `filter`, `source`) and the column. `declared_column_missing`: a field, measure, `filter`, join `on`/`using`, or query `source` reads a column its table no longer has. `declared_relation_missing`: the view's `source` (the whole view) or a join's `source` gone since the baseline. `declared_type_conflict`: a `date`/`date_time` format on a column that is not temporal, a number, currency, percentage or byte format on text, or `SUM`/`AVG` over text. `declared_dependency_dropped`: a field, measure (through `MEASURE()` too), window, or nested join that loses an input to another removal. A relation neither the connection nor the baseline lists, and an expression Dex cannot read, are named in `warnings` as unchecked |
| `volume` | unchanged: it reads the warehouse, not the layer |
| `grain` | measures each `rely.at_most_one_match` key (`declared_grain_not_unique`, worded as the view's claim and carrying `declared_by: databricks`, `claim: unique`, since Databricks trusts the flag and returns wrong numbers when it is false) and each join's declared arity (`join_cardinality_exceeded`, a `many_to_one` join whose joined side is not unique, `rely` or not) |
| `semantic` | definition drift free as everywhere: a view, measure or join added, removed or changed, and a field reading a column the warehouse no longer has. A view re-saved in a spec version Dex does not read is `semantic_format_changed` for that file, naming it and both versions; the other views are still compared by content |
| `reconcile` | the schema findings' removals are cut out of the view files and stored as a `semantic databricks update` plan under `data.semantic_plan_id`, validated by the reader before it is stored: each removed field, measure and join (a nested join goes with its parent), and a contradicted `format` (the member stays). Every other byte is kept and `on:` stays text. Advisory, never written: a view or join whose `source` is gone, a `filter` reading a dropped column (the view's population), a query `source` reading one, a removal a `materialization` names, one that would leave no field and no measure, and a file already holding a key Databricks refuses |
| `verify` | checks the dbt project only |

## Snowflake Semantic View layers (`semantic.vendor: snowflake`)

Every layer-neutral axis runs on a Semantic View layer, beside a dbt project or
with none, without a Snowflake connection to read it. The wrapper installs the
`[semantic-views]` extra for every `maintain` command where the vendor is
`snowflake`.

| Axis | On Semantic Views |
|---|---|
| `snapshot` | fingerprints each logical table (`view.table`, with its members' columns and its primary and unique keys, each key's claim recorded under `key_claims`: `primary` for `primary_key`, `unique` for each `unique_keys` entry), each table and view-level metric, and each key-equality relationship with its ordered pairs and arity (`many_to_one`, `one_to_one` or `many_to_many`); records `vendor: snowflake` and Dex's rule-set revision as `format_version`, and each table's primary key as its declaration (`declarations`), since a Semantic View has no metadata key. The hash covers a canonical form, so a view read back from Snowflake (upper-case names, defaulted `access_modifier` and `data_type`) fingerprints as its file |
| `schema` | adds the four `declared_*` codes, each naming the view, the element (`tables['orders'].dimensions['region']`, `tables['orders'].primary_key`, `relationships['orders_customers']`, `tables['paid'].base_table.definition`, `metrics['aov']`) and the column, from the metadata Dex captured with no Snowflake object created (#1293). `declared_column_missing`: a dimension, time dimension, fact or metric, a relationship's columns on either side, a `primary_key` or `unique_keys` entry, or a `base_table.definition` query reads a column its table no longer has. `declared_relation_missing`: a logical table's `base_table` gone since the baseline. `declared_type_conflict`: `SUM`/`AVG` over text (`high`: Snowflake creates the view and fails every query reading it), a time dimension over a column that is not temporal (`medium`: Snowflake answers with the column's values, so it is advised and never cut), and a declared `data_type` in another family than the warehouse's (`low`: Snowflake ignores it and records the column's own). `declared_dependency_dropped`: everything the reader would then refuse, to a fixpoint: a member reading a removed member, a member reading across a removed relationship, a derived metric reading a removed metric. A relation neither the connection nor the baseline lists, a `definition` Dex cannot read, and an expression the reader refused are named in `warnings` as unchecked |
| `volume` | unchanged: it reads the warehouse, not the layer |
| `grain` | measures each primary and unique key and each relationship's arity, worded as the view's claim with `declared_by: snowflake` and `claim` (`primary` or `unique` for a key, the arity for a relationship), since Snowflake trusts a declared key without checking it and a query through a relationship to a duplicated key counts its rows more than once. A key that never held is `declared_grain_not_unique`; one measurement proved unique at the baseline lapses as `key_lost_uniqueness` and names the claim too. `join_cardinality_exceeded` says Snowflake infers the arity from the referenced table's key. An ASOF or range relationship states no arity and is named unchecked |
| `semantic` | definition drift free as everywhere: a table, member, metric or relationship added, removed or changed. A changed primary key is `declaration_changed` on `grain`. A move to a newer pinned rule set is `semantic_format_changed`, not every definition changed |
| `reconcile` | the schema findings' removals are cut out of the view files and stored as a `semantic snowflake update` plan under `data.semantic_plan_id`, validated by the reader, strict rules included, before it is stored: each removed dimension, time dimension, fact, metric, derived metric and relationship, with the comments written directly above it, and a contradicted `data_type` (the member stays). An emptied list is written `[]`, which Snowflake accepts. Every other byte is kept. Advisory, never written: a logical table whose `base_table` is gone (never removed automatically), a key naming a dropped column, a `definition` query reading one, a time dimension over text, a removal the reader would refuse or that leaves the view no member, and a file already holding what authoring refuses. A key or relationship arity the data contradicts is advice naming `semantic snowflake update` |
| `verify` | checks the dbt project only |

A deployed semantic view is never inventoried: `SHOW VIEWS` does not list one,
and a plain `SELECT` on one fails, so no profile or grain probe reaches it.

## SLayer layers (`semantic.vendor: slayer`)

Every axis runs on a SLayer layer, and none opens a SLayer datasource or SLayer
storage: each reads the configured model files and the metadata Dex captured
through its own connection. The wrapper installs the `[slayer]` extra for every
`maintain` command where the vendor is `slayer`; without it a command refuses
with `reason: prerequisite` and names the install.

| Axis | On SLayer |
|---|---|
| `snapshot` | fingerprints each model (minus the values SLayer caches), each saved measure, each declared key, and each join with its ordered pairs and `cardinality`; records the vendor, the SLayer release and the model format version |
| `schema` | adds the four `declared_*` codes, SLayer's `validate-models` rules on Dex's metadata. A model backed by `sql` or `source_queries` is named as not compared |
| `volume` | unchanged: it reads the warehouse, not the layer |
| `grain` | measures every `primary_key` (a composite one whole) and `unique` column, and every join's declared `cardinality` (`join_cardinality_exceeded`); a join with none is named in `warnings` as unchecked |
| `semantic` | definition drift free as everywhere; the dimension-cardinality half re-counts every non-temporal column on the model's `sql_table` (offered as a scan on a billed connector) |
| `reconcile` | stores the `declared_*` removals as a second plan, `data.semantic_plan_id`, through `semantic slayer update`. A whole model is never removed; that and a type conflict's alternative stay advisory |
| `verify` | checks the dbt project only; SLayer's declared keys are measured by `grain`, not here |

What SLayer does not declare is not drift: it has no entities, no measures in
MetricFlow's sense (a saved measure is a formula), no per-measure time
dimension, and no `model_ref` (a model names its table directly). Read `unavailable` rather than reporting an
absent element kind.

Two things look like drift and are not:

- **A format-version mismatch in a file.** The reader refuses a model file in
  any format `version` but the pinned release's current one, names it in
  `warnings`, and its definitions come back as `definition_removed` because the
  file was not read. Repair the file with `semantic slayer update`, then re-run.
- **A release or format upgrade of the layer.** Reported once as
  `semantic_format_changed`, with definitions not compared by content until
  `maintain snapshot` baselines the new format. Added and removed definitions are
  still reported.

## What each axis costs

| Axis | Cost |
|---|---|
| `schema`, `volume`, semantic definitions | free metadata, everywhere |
| `grain`, semantic dimension cardinality | scans; billed handshake on a metered connector |
| `verify` build status | free (artifacts on disk) |
| `verify` row counts | free object metadata, except a view, which keeps no count: those are batched into one aggregate-only statement, priced, and returned in `data.offer` |
| `coverage` | free everywhere: a `dbt parse` of a copy, no connection |
| `coverage --mutate` | one `transform test --mutate` per stale or missing model, priced and confirmed once for the batch on a metered connector; free on DuckDB |
| `verify` declared facts | one aggregate statement per declared relation, plus one window probe per relation with an `additive` column; priced into the same single `data.offer` |

On DuckDB there is no gate, so `verify` measures every count and its findings
come back `exact`.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall