breaking-change-detector
Installation
SKILL.md
Breaking Change Detector
Audits breaking changes that could disrupt active sessions or lose client compatibility across 6 categories. Includes executable utilities for categories 1, 3, 5, and 6; categories 2 and 4 are checklist/static-analysis guided.
When to use: Modifying shared contract/interface packages, changing database schema or migrations, RPC/API endpoint signature changes, WebSocket message format changes, serialized state schema changes, before merging any contract/schema changes.
When not to use: Adding new optional fields (non-breaking), internal refactoring without API changes, documentation or test-only changes.
Rationalizations (Do Not Skip)
| Rationalization | Why It's Wrong | Required Action |
|---|---|---|
| "Nobody uses the old format" | Active sessions and stored data use the old format right now | Check backward compatibility |
| "We'll fix the clients" | Clients update on their own schedule, not yours | Keep old format supported |
| "It's just a rename" | A rename IS a removal + addition -- all consumers need updating | Deprecate, don't rename |
| "The migration handles it" | Migrations run once; replay/recovery may encounter old data indefinitely | Use tolerant reader pattern |