wit-breaking-change-check - SKILL.md Agent Skill

name: wit-breaking-change-check description: "Classify WIT interface changes as breaking or non-breaking against frozen version markers. Use this skill when the user wants to check WIT breaking changes, review a WIT diff, verify whether a WIT change is breaking, or run a WIT compat check. Trigger on: 'check WIT breaking changes', 'review WIT diff', 'is this WIT change breaking', 'WIT compat check'."

WIT Breaking Change Check

Classifies every modification in the current WIT diff against the breaking-change taxonomy and reports a verdict for each finding.

When to Use

Before merging any branch that touches wit/
When reviewing a PR that modifies WIT interface definitions
To verify a WIT change is safe before publishing a plugin-compatible release

Procedure

Run git diff origin/master -- wit/ to obtain the current diff.
For each wit/vN/ directory in the diff, check whether wit/vN/.frozen exists. If absent, report the version as experimental and skip it.
For each frozen version with changes, classify every modification against the breaking-change taxonomy in wit/VERSIONING.md:
- Breaking: removing/renaming any type, function, record field, or variant case; changing a function signature; changing a field type; reordering record fields; adding a required (non-optional) field to an existing record; adding a non-capability-gated required function to an existing interface.
- Non-breaking: new flags bits, new capability-gated functions, new record/variant/enum types, new interfaces, new worlds, @since/@unstable annotation additions.
Report each finding with a verdict:
- ✅ Non-breaking — with a brief reason citing the taxonomy
- ❌ Breaking — with a brief reason citing the taxonomy
- ⚠️ Uncertain — with the ambiguity explained
If any breaking change is found, summarize the required migration path for plugin authors.

Notes

The .frozen marker is a human-readable convention: its presence signals to reviewers and this skill that the version is stable and requires the breaking-change check before merge. Experimental (unfrozen) versions are skipped without a verdict.