| 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.
