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 |
Included Utilities
// Breaking change classification (zero dependencies)
import {
classifyFieldChange,
classifySerializedSchema,
classifyDeserializerSafety,
classifyEventTypeChanges,
classifyStatusCodeChanges,
classifyEnumValueChanges,
classifyApiFieldSemantics,
} from './breaking-change.ts';
Backward Compatibility Checklist
When modifying contracts or schemas:
- All existing fields preserved (or deprecated with fallback)
- New fields are optional or have
.catch()defaults - Type changes are widening only
- Database migration handles existing data
- Old event formats still supported for replay
- WebSocket protocol versioned
- API endpoints maintain compatibility
- Tests validate old data still deserializes correctly
- Serialized state schemas use
.catch()for all fields -
fromJSON()methods usesafeParse()with graceful fallback
Violation Rules
| Slug | Rule | Severity |
|---|---|---|
contract_field_removal | Removed/renamed fields in shared interfaces | must-fail |
schema_without_catch | Serialized schema fields missing .catch() default | must-fail |
strict_parse_in_deserialize | Using .parse() instead of .safeParse() in fromJSON | must-fail |
migration_drops_column | Column removal without data migration | must-fail |
endpoint_removed | API endpoint removed without deprecation period | must-fail |
event_type_renamed | Event type name changed (incompatible with replay) | must-fail |
Coverage
| Category | Utility | Status |
|---|---|---|
| 1. Contract fields | classifyFieldChange() | Code + tests |
| 2. Database schema | -- | Doc-only (requires SQL diffing) |
| 3. RPC/API endpoints | classifyStatusCodeChanges(), classifyEnumValueChanges(), classifyApiFieldSemantics() | Code + tests (API-level diff helpers) |
| 4. WebSocket protocol | -- | Doc-only (requires message schema diffing) |
| 5. Serialized state | classifySerializedSchema(), classifyDeserializerSafety() | Code + tests |
| 6. Event sourcing | classifyEventTypeChanges() | Code + tests |
Categories 2 and 4 require static analysis of SQL migrations or protocol schemas. Category 3 includes API-level helpers here, but full endpoint/spec diffing still needs OpenAPI/RPC schema tooling. See categories.md for detection commands and safe patterns.
Output Format
## CRITICAL -- Will Disrupt Active Sessions
### Contract: Removed UserState.score field
**File**: src/contracts/types.ts:42
**Impact**: Active sessions fail on state load
**Fix**: Deprecate instead:
/** @deprecated Use points instead */
score?: number;
points: number;
## WARNING -- Migration Required
### Database: Renamed column without migration
**File**: migrations/0036_rename_field.sql:5
**Impact**: Existing rows have NULL values
**Fix**: Add data migration step
## SAFE Changes
- Added optional field `UserState.metadata`
- New API endpoint `orders.archive`
- Widened type `Status: 'active' | 'paused'` to include `'archived'`
Companion Skills
This skill provides breaking change detection, not schema authoring or migration guidance. For broader methodology:
- Search
schema evolutionon skills.sh for migration strategies, versioning patterns, and backward compatibility tooling - Schema boundary validation pairs with breaking change detection — use zod-contract-testing for compound state matrices and schema evolution testing
- Serialized schemas with
.catch()defaults need structured error logging — use observability-testing to assert log output when old data triggers fallback paths
Framework Adaptation
This skill applies to any system with shared contracts/interfaces, persistent state, event sourcing, real-time protocols, or RPC/API layers with independent client release cycles.
See categories.md for detailed detection patterns, code examples, and safe alternatives for each of the 6 categories.