# Breaking Change Detector

> Audit 6 categories of breaking changes with executable checks for contracts, API diffs, serialized state, and event types.

- Skill: `jsgforever/breaking-change-detector` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jsgforever/breaking-change-detector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsgforever/breaking-change-detector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: jsgforever (https://skillmd.com/u/jsgforever)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsgforever/breaking-change-detector

---


# 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

```typescript
// 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](./references/categories.md) for detection commands and safe patterns.

## Output Format

```markdown
## 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](https://skills.sh) for migration strategies, versioning patterns, and backward compatibility tooling
- Schema boundary validation pairs with breaking change detection — use [zod-contract-testing](https://github.com/apankov1/quality-engineering/tree/main/skills/zod-contract-testing) for compound state matrices and schema evolution testing
- Serialized schemas with `.catch()` defaults need structured error logging — use [observability-testing](https://github.com/apankov1/quality-engineering/tree/main/skills/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](./references/categories.md) for detailed detection patterns, code examples, and safe alternatives for each of the 6 categories.