breaking-change-detector

name	breaking-change-detector
description	Detects breaking changes to public APIs, interfaces, and exported symbols, and blocks shipping without a migration path.
when_to_use	Apply automatically when modifying any public API, exported function, interface, event schema, or shared contract.

Breaking Change Detector Skill

A breaking change is any modification that requires consumers of your code to change their code to keep working. Breaking changes in internal platform code, shared libraries, or public APIs are a leading cause of cross-team incidents and deployment coordination failures.

This skill detects them before they ship.

What Counts as a Breaking Change

Always breaking:

• Removing a function, method, class, or exported symbol
• Removing a required field from a request schema
• Adding a required field to a request schema (consumers that do not send it will fail)
• Changing a return type or response schema in a way that removes fields
• Changing the meaning of an existing field (same name, different semantics)
• Changing error codes, error shapes, or error response formats
• Changing event names or event payload schemas in message queues or event buses

Breaking depending on consumers:

• Renaming a function or endpoint without an alias or redirect
• Changing default values of optional parameters
• Narrowing the accepted input range (was: any string, now: max 255 chars)
• Adding a new enum value that consumers must handle exhaustively

Non-breaking:

• Adding optional fields to a request schema
• Adding new endpoints or methods
• Adding new optional parameters with sensible defaults
• Widening the accepted input range

Required Output

When a breaking change is detected:

## Breaking Change Detected

**Symbol / endpoint / schema changed:** [name]
**Change type:** [removed / signature changed / schema changed / renamed]
**Classification:** [BREAKING / POTENTIALLY BREAKING]

### What Breaks
[Describe concretely what stops working for consumers of this interface.]

### Known Consumers
[List files, services, or teams that depend on this contract, based on codebase search.]
[If consumers are external (API clients, other services), flag that the blast radius is unknown.]

### Migration Path Required
Choose one of the following before this change merges:

Option A — Versioned migration
  Add a v2 endpoint / v2 interface alongside v1.
  Deprecate v1 with a sunset date.
  Remove v1 only after all known consumers have migrated.

Option B — Compatibility shim
  Keep the old signature as a wrapper that calls the new one.
  Mark it @deprecated with a migration note.
  Schedule removal for [next major version or sprint].

Option C — Coordinated cutover
  All consumers are internal and can be updated in the same PR or deployment window.
  List every consumer that must be updated, and confirm all are included in this change.

Option D — Explicit breaking release
  This is an intentional breaking change in a major version bump.
  Confirm: semver major version has been incremented.
  Confirm: CHANGELOG entry documents the break and the migration path.
  Confirm: consumers have been notified.

### Verdict
[BLOCKED — choose a migration option above before proceeding]

Semver Enforcement

When a breaking change is confirmed and approved:

• Verify the version in package.json, pyproject.toml, go.mod, Cargo.toml, or equivalent has been bumped to the next MAJOR version
• If it has not, flag it and refuse to mark the task complete until versioning is updated

Changelog Entry

For every confirmed breaking change, generate a CHANGELOG entry:

## [MAJOR.0.0] - [date]

### Breaking Changes

- **[symbol/endpoint name]**: [what changed and why]
  - **Migration:** [what consumers need to do]
  - **Removed in:** [this version]
  - **Deprecated since:** [prior version, if applicable]