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 use safeParse() 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 evolution on 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.