From dataproduct-builder-databricks
Edit an output-port ODCS file under src/output_ports/v<N>/, run the contract test against the live data, and classify any failures as breaking or non-breaking changes — with suggested fixes. Only edits output-port contracts (the spec this data product commits to); input-port contracts under src/input_ports/ are upstream's responsibility and refreshed by dataproduct-implement. Trigger when the user asks to "add/remove/change a column in the data contract", "update the data contract", or "test contract changes".
How this skill is triggered — by the user, by Claude, or both
Slash command
/dataproduct-builder-databricks:datacontract-editThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Change an output-port `src/output_ports/v<N>/*.odcs.yaml` file, run the contract test, and tell the user whether the change breaks consumers.
Change an output-port src/output_ports/v<N>/*.odcs.yaml file, run the contract test, and tell the user whether the change breaks consumers.
This skill operates only on output-port contracts — the spec this data product commits to. Input-port contracts under src/input_ports/ are cached snapshots of upstream's spec and are not editable here; if you want to refresh one (because upstream changed it), run dataproduct-implement instead.
Before running Step 0, print this plan to the user verbatim:
Running datacontract-edit. I'll:
- Locate the output-port contract file under
src/output_ports/v<N>/that matches your request.- Apply the edit in place and show you a unified diff.
- Run
datacontract testagainst the live server to check the change.- Classify each failure as breaking-schema, breaking-quality, additive, or unrelated.
- Report and suggest concrete fixes (no version bump, no v2 directory, no pipeline changes).
Then proceed.
src/output_ports/**/*.odcs.yaml — never src/input_ports/. If the user names an input-port contract, stop and explain it can't be edited here (refresh via dataproduct-implement instead).src/output_ports/.schema / models block as BEFORE.Edit the ODCS YAML in place using the user's instruction. Keep the change minimal — do not reformat unrelated fields.
Common edits and the right shape:
| User says | What to change |
|---|---|
| "add column X" | Append a field under the relevant model with at least type; set required: false by default unless the user says it's required |
| "remove column X" | Delete the field; this is breaking — flag in Step 4 |
| "rename X to Y" | Rename the field; this is breaking — flag |
| "make X required" | Add required: true; breaking if existing rows can be null |
| "change X type from int to string" | Update type; breaking unless the new type is a strict superset (e.g. int → bigint) |
| "add a unique/not_null/enum check" | Add to the field's quality rules; breaking iff existing data violates the new rule — only Step 2 can tell |
After editing, remember the new block as AFTER and show the user a unified diff before continuing.
Run the test with the datacontract CLI against the local contract file:
uv run datacontract test src/output_ports/v<N>/<file>.odcs.yaml --server <server> --logs
production). Default to all only if the user explicitly asks.--logs so failure detail is in the output you read; otherwise the CLI only prints a summary.--output ./test-results/results.json --output-format json so the JSON artifact exists for the optional Step 2b publish. (entropy-data test-results publish reads JSON or YAML; JUnit XML is not accepted.)TEST_RESULT. Non-zero exit means at least one rule failed; the log section names the failing field/rule.Pre-reqs the CLI needs (verify before running, fail fast with a clear message if missing):
uv run --quiet datacontract --version succeeds from the project root. If it fails, run uv sync and retry. Invoke as uv run datacontract test … for every CLI invocation in this skill.DATACONTRACT_DATABRICKS_TOKEN + DATACONTRACT_DATABRICKS_HTTP_PATH for Databricks). Tell the user which env vars are missing — do not try to source them yourself.Do not use the platform's server-side contract-test endpoint from this skill. The local datacontract CLI runs against the edited file and gives line-level failure detail; testing the published version on the server would test the previous contract, which defeats the point of testing the edit.
This is an output-port contract — results belong in the platform's Data Quality panel.
Ask the user — required confirmation gate:
Publish the test results to Entropy Data so they show up in the Data Quality panel for
<CONTRACT_ID>? (yes / no)
If no, mark publish as skipped in Step 4. Do not publish without an explicit ask — this writes server-side state.
If yes:
uv run entropy-data test-results publish --file ./test-results/results.json
Capture stdout + exit code. On failure, surface the error in the final report but do not retry — the edit and its local test outcome are still the user's primary signal.
Group every failure into one of these buckets:
| Bucket | Examples | Severity |
|---|---|---|
| Breaking — schema | column removed, type narrowed, column renamed | High — bump major version, deprecate old port |
| Breaking — quality | new not_null/unique/enum rule violated by existing data | High — clean data first, then re-test |
| Non-breaking — additive | new optional column, widened type, loosened rule | Low — minor version bump |
| Test failure unrelated to the edit | flaky source, infra error, unchanged rule failing | Investigate separately |
For each failure, name the exact field/rule and which bucket it falls into. Don't lump them together.
End with this two-part recap. The Status column uses the shared enum (AGENTS.md § Final-report Status enum), and below it a classification table covers any test failures.
Part 1 — outcome table.
| Artifact | Status | Details |
|---|---|---|
| Contract file | updated | src/output_ports/v<N>/<file>.odcs.yaml — show the unified diff inline |
| Contract test | … | pass, fail (<N> failures), or not run (missing creds) — name the server |
| Test results published to Entropy Data | … | published / skipped (user declined) / failed: <error> |
| Breaking — schema | … | count of failures in this bucket, or "—" |
| Breaking — quality | … | count of failures in this bucket, or "—" |
| Non-breaking — additive | … | count of changes in this bucket, or "—" |
| Test failures unrelated to the edit | … | count, or "—" |
| Recommended version bump | … | patch / minor / major based on the edit |
For the four "bucket" rows, leave Status = — and put the failure count + a one-line bucket description in Details.
Part 2 — next steps. Per failure, give a concrete fix suggestion:
src/output_ports/v2/), keep v1 alive, add a deprecation note in <id>.odps.yaml.version minor, no consumer impact. If the new column needs to flow through the Lakeflow pipeline, point at dataproduct-implement to regenerate the @dp.table definition.Do not auto-bump the contract version, do not create v2/ directories, and do not modify pipeline code. Surface the recommendation; let the user decide.
dataproduct-implement after this skill.entropy-data datacontracts get <id> -o yaml redirected to the file).npx claudepluginhub entropy-data/dataproduct-builder-databricks --plugin dataproduct-builder-databricksGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.