agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/dbt-transformation-adapter/SKILL.md

dbt-transformation-adapter

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Run dbt as the build ENGINE for silver/gold ONLY behind the Mapping Ready gate, and record its run/test/parity output as DERIVED evidence -- never as an approval. Use when someone asks to build silver/gold for a mapped table with dbt, run dbt tests, or check dbt parity against the existing gold tables in the Seshat BI repo. dbt is the engine; Seshat BI is the brain. This skill READS the approved map, EXECUTES approved dbt steps behind the gate, and WRITES evidence; it never defines meaning, never moves a stage to pass, and HARD-STOPS at every human judgment call.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    STOP and escalate to a named human.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

dbt-transformation-adapter

  • Authority category (F024): Execution Adapter / DB-connected (NOT publish-capable).
  • Roadmap feature: F029 On-disk spec: specs/023-dbt-transformation-adapter.

dbt is the build ENGINE: it compiles SQL, materializes models, and runs tests. Seshat BI is the brain: it owns the approved source-map, the metric contracts, and the readiness spine, and routes every judgment call to a named human. This skill is how the agent runs dbt without letting it become the brain. You (the agent reading this) ARE the runtime; this skill is procedure, not an engine -- there is no daemon, no scheduler, no auto-approver. See docs/decisions/0009-dbt-is-transformation-adapter.md and templates/dbt-adapter-contract.md.

ACTIVATED: feature 133 added the governed runtime under dbt/, the pinned dbt-core==1.12.0 + dbt-postgres==1.10.2 extra, and the seshat dbt command family. Use that wrapper only; raw dbt commands bypass the accepted-plan, selector, shadow-schema, redaction, lock, and evidence contracts.

Scope boundary (read first)

Invoke-and-record only. This skill runs dbt behind the gate and records its findings as evidence; it does NOT define source mapping, metric contracts, or semantic logic, does NOT publish Power BI, and does NOT move a readiness stage to pass. Three non-negotiables:

This adapter is not the owner of generic dbt competence. Model-authoring advice, generic test design, command syntax, documentation lookup, MCP configuration, and troubleshooting belong to the official dbt Labs agent skills and dbt MCP. Official-skill activation and discovery must be proven by the Spec 148 harness probe before routing to those skills; MCP liveness remains a separate preflight fact. This skill owns only Seshat's governed pre-gate, invocation policy, evidence normalization, parity interpretation, and human-stop seams around the official dbt Core executor; it must not reproduce upstream instructions.

  • The entry gate is the FIRST refusal point (Principle IV). The canonical gate signal is mappings/<table>/readiness-status.yaml -> stages.mapping_ready.status == pass WITH a matching approvals[] entry (RS1); its human-readable mirror unresolved-questions.md Gate status: CLEARED (zero open rows) MUST agree. dbt may run NO staging/silver/gold model unless that canonical signal holds -- a missing readiness-status file, mapping_ready != pass, or a mismatch between the two -> Refuse + record a blocking_reason. The presence of dbt model files is NOT permission to build.
  • A green dbt test is EVIDENCE, never an approval (the governance hinge). Record the pass/fail counts as evidence[] / blocking_reasons[]; Tower readiness + a named human move Silver/Gold Ready to pass, citing that evidence + the approval. There is NO path by which a green run alone writes pass.
  • dbt stops at gold (Principle III). dbt is DB-connected, not publish-capable; materializing/publishing a Power BI model is the parked F016 adapter, gated separately.

ASCII only, UTF-8 no BOM in everything you author (--, ->; no em-dash / smart-quote / unicode-arrow).

Run-state: read mappings/<table>/ FIRST (no new state file)

Compute what you may do from what is already on disk -- there is NO dbt orchestration state file to create:

What you observeAction
mappings/<table>/readiness-status.yaml missing, or stages.mapping_ready.status != pass, or its approvals[] entry is absent, or the unresolved-questions.md Gate status: CLEARED mirror does not agreeREFUSE. Record a blocking_reason ("Mapping Ready not pass"); run no model.
stages.mapping_ready.status == pass WITH a matching approvals[] entry, the Gate status: CLEARED mirror agrees, approved source-map.yaml presentPermitted to run staging/silver/gold models that CITE the approved map.
A dbt model builds a meaning (grain/PK/PII/placement) the map does NOT stateDEFECT. The model cites the map, it does not extend it; the map is re-approved first.
The table is already built by migrationsThe dbt mart must pass the reconciliation parity test before it can become the build path.

You may READ Mapping Ready; you may NOT write pass to any stage (that is the named human's action). Read the approved map by path + git ref; every model must cite it.

Fixed sequence (use the governed wrapper only)

StepWhat you doAuthority note
1 PrerequisitesRun seshat dbt doctor --format json. It queries no database.Missing runtime/profile values -> [PENDING LIVE PROFILE].
2 Gate + citationsRun seshat dbt validate --table <table> --format json.Refuses before planning unless Mapping Ready has the named-human approval and every selected model cites it.
3 Immutable planRun seshat dbt plan --table <table> --format json; review the exact nodes, target, versions, mapping identity, and shadow schemas.The returned digest accepts execution, not business meaning or readiness.
4 BuildRun seshat dbt build --table <table> --accept-plan <digest> --format json.Recomputes the plan before DB access; drift refuses execution.
5 Test-only rerunWhen needed, run seshat dbt test --table <table> --accept-plan <digest> --format json.Evidence, never approval.
6 Offline reviewFor an existing run directory, run seshat dbt inspect-run --table <table> --artifacts <run-directory> --format json.Revalidates artifacts; it is not a second build.
7 Recommend + STOPReport normalized evidence and blocking_reasons, then stop for a named human.Never self-approve or switch away from migrations.

The reconciliation parity test (four assertions, exact to the cent)

For a table already built by migrations, assert against the migration-built gold fact:

  1. equal fact row count;
  2. preserved distinct count of the fact's degenerate / business key;
  3. each additive money-measure sum equal to the cent -- absolute delta <= 0.01 per additive measure, matching the committed money scale (e.g. NUMERIC(12,2));
  4. equal per-dimension distinct member counts -- each conformed dimension's member count, including any unknown / sentinel member where the gold model defines one.

A mismatch -> record the measured delta as a blocking_reason, keep Gold Ready blocked, keep migrations the default. After an approved switch, the migration files are RETAINED as the parity oracle; the parity test RE-RUNS on EVERY dbt build while the oracle is retained (never one-time-at-switch). The cent tolerance is the stated default -- NOT a score.

HARD-STOP: the Principle V judgment calls (never auto-resolve)

STOP and escalate to a named human; record an owner row -- do not edit around any of these:

  • a grain ambiguity, or a model that would change the declared grain (e.g. collapse line items) -- forbidden without a re-approved map.
  • a sentinel-vs-null choice (e.g. an unknown-member handling that diverges from the migration's sentinel -- the parity test catches the divergence; resolving it is a human call).
  • a PII publish-safety question on any column.
  • a business rollup / segment mapping the map does not answer.
  • moving Silver Ready / Gold Ready to pass -- always a named-human approval, never a green dbt test.
  • a build-path switch (migrations -> dbt) -- only after parity passes AND a human approves; never flip the default on your own; never delete the migration oracle.
  • any dbt-core / dbt-postgres major (and, until compatibility tests exist, minor) version bump -- a named reviewer approves; no automerge.

Live and downstream seams (report and stop, never fake)

  • A live dbt run -- needs the dbt extra, a DB, and SESHAT_DBT_* values in the gitignored .env; committed profiles.example.yml contains only env_var() references. Without them, report [PENDING LIVE PROFILE], the enable steps, and no compile/build/test/parity success.
  • The Power BI build -- F016 (parked, publish-capable, gated on Semantic Model Ready); dbt stops at gold and does not touch it.

At a seam: state plainly what is deferred, what would unblock it, and STOP.

See also

  • The decision record: docs/decisions/0009-dbt-is-transformation-adapter.md.
  • The contracts: templates/dbt-adapter-contract.md, templates/dbt-model-contract.md.
  • The integration doc + the governed dbt/ runtime: docs/integrations/dbt-adapter.md.
  • The example connection profile: profiles.example.yml (placeholders only).
  • The category contract: docs/architecture/product-modules.md; the copy-me Adapter declaration: templates/adapter-contract.md.
  • The planning history: specs/023-dbt-transformation-adapter/; the activation implementation: specs/133-activate-dbt-mvp/.
  • .specify/memory/constitution.md (Principles III, IV, V, VI, VII, VIII, IX).
  • The filled first-MVP instance is CITED, never inlined: a worked example under docs/worked-examples/.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.