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
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- approval-evidence-packSkill
- business-knowledge-interviewSkill
- capabilitiesSkill
- consumer-data-dictionarySkill
- cross-table-lineageSkill
- dagster-orchestration-adapterSkill
- dashboard-designSkill
- dashboard-intelligenceSkill
- evidence-pack-generatorSkill
- first-hour-compassSkill
- friendly-pr-reviewerSkill
- grain-confidence-reviewerSkill
- kpi-contract-builderSkill
- pbi-mcp-write-adapterSkill
- pbip-workflowSkill
- pbip-xraySkill
- pbir-authoring-adapterSkill
- portfolio-watchSkill
- powerbi-dashboard-designSkill
- pr-readiness-reviewerSkill
- readiness-viewerSkill
- release-notes-generatorSkill
- report-intent-interviewSkill
- retail-build-warehouseSkill
- retail-control-roomSkill
- retail-discover-portfolioSkill
- retail-governSkill
- retail-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- retail-validateSkill
- run-next-readinessSkill
- seshat-studioSkill
- showcase-buildSkill
- source-mappingSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- bi-analyst-knowledgeSkill
- bi-bigdata-knowledgeSkill
- bi-dax-knowledgeSkill
- bi-python-knowledgeSkill
- bi-sql-knowledgeSkill
- retail-kpi-knowledgeSkill
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
- Distinctive: line 108
STOP and escalate to a named human.
≈ “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.
Files
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 pinneddbt-core==1.12.0+dbt-postgres==1.10.2extra, and theseshat dbtcommand 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 == passWITH a matchingapprovals[]entry (RS1); its human-readable mirrorunresolved-questions.mdGate 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 ablocking_reason. The presence of dbt model files is NOT permission to build. - A green
dbt testis EVIDENCE, never an approval (the governance hinge). Record the pass/fail counts asevidence[]/blocking_reasons[]; Tower readiness + a named human move Silver/Gold Ready topass, citing that evidence + the approval. There is NO path by which a green run alone writespass. - 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 observe | Action |
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 agree | REFUSE. 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 present | Permitted 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 state | DEFECT. The model cites the map, it does not extend it; the map is re-approved first. |
| The table is already built by migrations | The 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)
| Step | What you do | Authority note |
| 1 Prerequisites | Run seshat dbt doctor --format json. It queries no database. | Missing runtime/profile values -> [PENDING LIVE PROFILE]. |
| 2 Gate + citations | Run 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 plan | Run 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 Build | Run seshat dbt build --table <table> --accept-plan <digest> --format json. | Recomputes the plan before DB access; drift refuses execution. |
| 5 Test-only rerun | When needed, run seshat dbt test --table <table> --accept-plan <digest> --format json. | Evidence, never approval. |
| 6 Offline review | For 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 + STOP | Report 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:
- equal fact row count;
- preserved distinct count of the fact's degenerate / business key;
- each additive money-measure sum equal to the cent -- absolute delta
<= 0.01per additive measure, matching the committed money scale (e.g.NUMERIC(12,2)); - 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 greendbt 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
dbtextra, a DB, andSESHAT_DBT_*values in the gitignored.env; committedprofiles.example.ymlcontains onlyenv_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/.
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
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.

