/maintain

name: maintain
description: 'Use this to keep a dbt project and its semantic layer correct as the warehouse and the business change, including a semantic layer that is native Apache Ossie documents rather than dbt. It detects drift on four axes and proposes the fix: schema drift (source columns and tables added, dropped, retyped, or renamed), volume drift (a row count that collapsed, a table that emptied, a load that half-failed), grain drift (a key that lost uniqueness, a changed row-per-entity cardinality, an increased join fanout), and semantic drift (a metric, measure, dimension, or entity definition that no longer matches, new categorical values, dangling semantic references). Reach for this when something that used to work has started failing or producing different numbers and the cause is more likely upstream than in the code you just wrote: a test that began failing with no code change, a dashboard whose numbers moved, a model that is suddenly empty or duplicated. Trigger it for requests like "what changed in the warehouse", "did anything drift", "is my dbt project still in sync", "my primary key has duplicates now", "the row count dropped", "did the load run", "the data stopped flowing", "the revenue metric definition changed", "reconcile my models with the source schema", "which models are stale", "did my Ossie semantic layer drift", or "is this relationship still valid". It reads the .dex/ snapshot and proposes reviewable diffs; it never overwrites hand-written work. To author new models or metrics from scratch, use transform. To learn an unfamiliar warehouse for the first time, use explore.'

Maintain

Keep the repository correct as the world underneath it moves, on both of its axes: the dbt project and the semantic layer. Maintenance is the recurring half of the loop: warehouses drift, loads half-fail, models go stale, keys stop being unique, and business definitions change. This skill compares a known-good baseline against current reality, classifies what drifted, and proposes the reconciling edit. It is manual and on-demand here; continuous drift detection and automated PRs are the commercial product.

The model: baseline, detect, reconcile

Drift is measured against a **baseline** (the `.dex/snapshot.json` fingerprint of the warehouse map and the repository's per-layer definitions). Detection is read-only; only reconcile proposes edits.

**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. A repository with a semantic layer and no dbt project at all still gets a baseline and still runs every free axis: `transform_layer` comes back null, and the warning that names why no project was fingerprinted is reserved for the case where neither layer answered, since that is the one you could otherwise mistake for a clean read.

**Snapshot discipline matters.** A snapshot is only as trustworthy as the moment it froze. Take one right after a known-good build (`maintain snapshot`), and **commit `.dex/snapshot.json` like a lockfile** so the whole team diffs against the same reference. Snapshot a state that is already drifted and `check` will mask the very drift you care about. When you accept a change as the new normal (re-run `explore map` first, then `maintain snapshot`); `check` warns when the baseline looks stale.

**On a warehouse past the rank cutoff, use `explore map --full` before snapshotting.** Past 50 objects `explore map` profiles the top 25 by rank and enters the rest as metadata alone, and the baseline can only compare columns for objects it has columns for. Snapshotting a partial map is still valid, and the envelope reports `column_detail_count` against `dataset_count` plus a warning naming what it could not cover, so the gap is visible rather than silently mistaken for a clean bill.

How to drive it

uv run --no-project --script "${CLAUDE_SKILL_DIR}/scripts/run.py" <subcommand> [flags]

dex runs its engine through `uv`, which is a prerequisite and is not installed by Claude Code. If the shell reports `uv: command not found`, stop and tell the user to install it (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `brew install uv`, or `pipx install uv`), then re-run. Never fall back to diffing the warehouse against the project by hand instead: the drift axes and the baseline comparison live in the engine, so any other path is guesswork.

The first command in a fresh environment installs the engine, so it can take tens of seconds where later ones take well under a second. `--warm` pays that install up front and exits without running anything:

uv run --no-project --script "${CLAUDE_SKILL_DIR}/scripts/run.py" --warm

Offer it once at setup. It is not something to run before an ordinary command.

• `maintain snapshot` captures or refreshes the baseline. Run it after a clean

explore or transform session so later runs have a known-good reference. It 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. 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. Without a cache it captures a metadata-only baseline and says so. It also warns when the cache it pinned is thin (objects without column detail) or older than the profile freshness window, because either makes an "accept current state" only partly true.

• `maintain snapshot --pro