Datacontract Edit

Edit a data contract and test the impact

Change an output-port models/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 models/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.

How to run this skill

${PLUGIN_ROOT} below refers to the root of this plugin — the directory that contains skills/. On Claude Code it is set automatically as ${CLAUDE_PLUGIN_ROOT} — use that. On any other agent (Codex, Copilot CLI, etc.) it is unset; resolve it as ../.. relative to this SKILL.md file's directory (i.e. the grandparent of skills/<this-skill>/).

Plan announcement (before Step 0)

Before running Step 0, print this plan to the user verbatim:

Running datacontract-edit. I'll:

1. Locate the output-port contract file under models/output_ports/v<N>/ that matches your request.
2. Apply the edit in place and show you a unified diff.
3. Run datacontract test against the live server to check the change.
4. Classify each failure as breaking-schema, breaking-quality, additive, or unrelated.
5. Report and suggest concrete fixes (no version bump, no v2 directory, no dbt model changes).

Then proceed.

Step 0 — Locate the contract

• Search only models/output_ports/**/*.odcs.yaml — never models/input_ports/. If the user names an input-port contract, stop and explain it can't be edited here (refresh via dataproduct-implement instead).
• If the user named a contract file or column, find the matching file under models/output_ports/.
• If multiple contracts exist and it's ambiguous, list them and ask which one.
• Read the file and remember the current models block as BEFORE.

Step 1 — Apply the edit

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:

After editing, remember the new models block as AFTER and show the user a unified diff before continuing.

Step 2 — Run the contract test

Run the test with the datacontract CLI against the local contract file:

datacontract test models/output_ports/v<N>/<file>.odcs.yaml --server <server> --logs

• If the contract has more than one server, ask which one (typically production). Default to all only if the user explicitly asks.
• Use --logs so failure detail is in the output you read; otherwise the CLI only prints a summary.
• If the user wants the report persisted, add --output ./test-results/junit.xml --output-format junit.
• Capture stdout + exit code as 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.
• The chosen server's credentials available as env vars per the ODCS server block (e.g. DATACONTRACT_SNOWFLAKE_USERNAME / ..._PASSWORD, or DATACONTRACT_DATABRICKS_TOKEN). 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.