Claude Skill

drift-canary

Compatibility and schema drift canary — checks for database schema migration safety, breaking API contract changes, serializable payload mismatches, and backward compatibility drift. Triggers on keywords: "/drift-canary", "drift-canary", "contract drift", "breaking changes". Use

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download hetcreep-coalmine-skills_drift-canary-85306d7.zip · 3 KB

hetcreep/coalmine 13 2 forks Apache-2.0 Updated 7d ago

Part of hetcreep/coalmine — 18 skills

Install

skills CLI npx skills add https://github.com/TheColliery/CoalMine/tree/main/skills/drift-canary

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install hetcreep-coalmine@llmmart

Git git clone https://github.com/TheColliery/CoalMine.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole hetcreep/coalmine collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Drift Canary (Contract & Schema Drift Audit)

Audit code to ensure changes do not break backward compatibility or cause database/API mismatches.

Auditing Categories

Breaking Schema Migrations — dropping columns, changing types, or adding non-null columns without defaults (crashes on deploy).
API Contract breaking changes — modifying existing REST/GraphQL properties, removing endpoints, or adding required query fields that break old clients.
Serialization mismatches — editing properties in serialized payloads (JSON, Protobuf, XML) without deserialization fallbacks.
Library Contract Drift — changing a public method signature in a shared library without a deprecated wrapper.
Environment Configuration drift — introducing new required config keys (.env / OS vars) without defaults or fallback.

Expand/contract migration rules, per-format serialization fallbacks, and the breaking-vs-additive API checklist: read references/checks.md before scanning.

Scope: honor .coalmine.json schemaPaths / migrationDirs if set — scan those globs/dirs; else infer by inspecting the repo.

Discipline

Style Drift Resolution (Fix mode): when an approved fix touches mixed-style code, conform the minority patterns to the dominant style (highest average usage) to minimize churn — never start a standalone style refactor.

Fix mode (choice-gated)

In Agent Context, after the report, present via ask_question:

Apply safe deprecations: mark endpoints/methods deprecated + add backward-compatibility mapping wrappers. Each fix: checkpoint (git stash/commit in a git repo; else copy the file aside — never assume git) → apply → build + tests → auto-revert if newly red.
Let me pick: user selects specific compatibility fixes.
Report only: exit unchanged.

Grants & denials (CLASSIFY-BLOCK)

class	step it powers	grant	on denial
read	scan schema/API/serialization surfaces for the categories above	`Read`·`Grep`·`Glob`	refuse that file, name it — never a clean bill
write	Fix mode's deprecation/compat-wrapper apply, incl. checkpoint → build+tests → auto-revert if newly red	`Edit`·`Bash` (checkpoint/build/revert need exec)	report the fix as NOT applied AND the checkpoint/revert as NOT available, never claim done

Output

Severity: CRITICAL (breaking DB schema mutation / breaking API change) · HIGH (serialization type change) · MEDIUM (unmapped new required env key) · LOW (missing deprecation doc)

Files (coalmine)

references

checks.md 2.3 KB

<!-- coalmine: verified 2026-06-12 · revalidate 90d · definition file for drift-canary -->
# Drift canary — concrete detection procedures

## 1. Breaking schema migrations — expand/contract rule
Safe order (expand → migrate → contract; never combined in one release):
1. **Expand:** add nullable column / new table / new index — old code keeps working.
2. **Migrate:** backfill data; deploy code that writes both / reads new-with-fallback.
3. **Contract:** only after all writers upgraded — add NOT NULL, drop old column.

Flag as CRITICAL in one migration: `DROP COLUMN`/`DROP TABLE` still referenced by deployed code · type narrowing (`TEXT→INT`, shrinking varchar) · `ADD COLUMN ... NOT NULL` without `DEFAULT` on a populated table · renames (= drop+add to every old client).

## 2. Breaking API contract changes
Breaking (flag): removing/renaming an endpoint, field, or enum value · changing a field's type/format · making an optional param required · changing error shape/status codes clients branch on.
Safe (additive): new optional field · new endpoint · new enum value IF clients tolerate unknowns (verify!).
Check: OpenAPI/GraphQL schema diff if present; otherwise diff DTO/serializer classes.

## 3. Serialization mismatches
- JSON: removed/renamed properties without alias support (`[JsonPropertyName]`, `@JsonAlias`, serde `alias`) · strict deserializers that throw on unknown fields meeting a newer producer.
- Protobuf: field NUMBER reuse or type change (wire-breaking) — numbers must be `reserved` after deletion; new fields = new numbers.
- Queues/events: producer upgraded before consumers — old messages still in flight must deserialize.

## 4. Library contract drift (shared/public libs)
- Public signature changes without `[Obsolete]`/`@deprecated` wrapper for one release window.
- Behavior changes under an unchanged signature (return null→throw) — worse than signature breaks; flag.
- SemVer: breaking change without major bump.

## 5. Config drift
- New required env/config key read with no default and no startup validation → first crash happens in production.
- Right shape: default value, or fail-fast at startup with the exact missing-key name, plus README/.env.example entry.

## Migration-path column (output)
Each finding names its safe path: expand/contract step · alias/reserved-number · deprecated wrapper · default+validate.

skill-meta.json 195 B

{ "lightIntent": "Spot contract check, key interfaces only", "standardIntent": "Balanced drift audit, multi-category", "heavyIntent": "Full 5-category audit + adversarial compatibility verify" }

SKILL.md 3.1 KB

---
name: drift-canary
description: >-
  Compatibility and schema drift canary — checks for database schema migration safety, breaking API contract changes, serializable payload mismatches, and backward compatibility drift. Triggers on keywords: "/drift-canary", "drift-canary", "contract drift", "breaking changes". Use when changing DB schemas, API contracts, serialized payloads, or required config keys.
---

# Drift Canary (Contract & Schema Drift Audit)

<!-- SHARED:LANGUAGE_HEADER -->

Audit code to ensure changes do not break backward compatibility or cause database/API mismatches.

## Auditing Categories
1. **Breaking Schema Migrations** — dropping columns, changing types, or adding non-null columns without defaults (crashes on deploy).
2. **API Contract breaking changes** — modifying existing REST/GraphQL properties, removing endpoints, or adding required query fields that break old clients.
3. **Serialization mismatches** — editing properties in serialized payloads (JSON, Protobuf, XML) without deserialization fallbacks.
4. **Library Contract Drift** — changing a public method signature in a shared library without a deprecated wrapper.
5. **Environment Configuration drift** — introducing new required config keys (`.env` / OS vars) without defaults or fallback.

Expand/contract migration rules, per-format serialization fallbacks, and the breaking-vs-additive API checklist: read `references/checks.md` before scanning.

**Scope:** honor `.coalmine.json` `schemaPaths` / `migrationDirs` if set — scan those globs/dirs; else infer by inspecting the repo.

## Discipline
- **Style Drift Resolution (Fix mode):** when an approved fix touches mixed-style code, conform the minority patterns to the dominant style (highest average usage) to minimize churn — never start a standalone style refactor.

## Fix mode (choice-gated)

In Agent Context, after the report, present via `ask_question`:

- **Apply safe deprecations:** mark endpoints/methods deprecated + add backward-compatibility mapping wrappers. Each fix: checkpoint (git stash/commit in a git repo; else copy the file aside — never assume git) → apply → build + tests → auto-revert if newly red.
- **Let me pick:** user selects specific compatibility fixes.
- **Report only:** exit unchanged.

## Grants & denials (CLASSIFY-BLOCK)
| class | step it powers | grant | on denial |
|---|---|---|---|
| read | scan schema/API/serialization surfaces for the categories above | `Read`·`Grep`·`Glob` | refuse that file, name it — never a clean bill |
| write | Fix mode's deprecation/compat-wrapper apply, incl. checkpoint → build+tests → auto-revert if newly red | `Edit`·`Bash` (checkpoint/build/revert need exec) | report the fix as NOT applied AND the checkpoint/revert as NOT available, never claim done |

<!-- SHARED:CLASSIFY_BLOCK -->

## Output
`| file:line | contract interface | severity | finding | migration path |`

Severity: CRITICAL (breaking DB schema mutation / breaking API change) · HIGH (serialization type change) · MEDIUM (unmapped new required env key) · LOW (missing deprecation doc)

<!-- SHARED:REPORTING_FOOTER -->

<!-- SHARED:ORCHESTRATION -->

<!-- SHARED:ESCALATION_FOOTER -->