breaking-change-detector

<objective>
The breaking-change-detector skill prevents breaking changes from reaching production by detecting potentially breaking API, schema, and interface modifications before implementation.

Breaking changes destroy trust and break client applications:
- Removing API endpoints breaks existing integrations
- Changing request/response formats breaks client code
- Dropping database columns causes data loss
- Modifying function signatures breaks dependent code
- Changing authentication schemes locks out users

This skill acts as a safety gate that:
1. **Detects** breaking changes before they're implemented
2. **Warns** developers with severity levels (CRITICAL, HIGH, MEDIUM)
3. **Suggests** safe migration paths (versioning, deprecation, backward compatibility)
4. **Validates** changes against project's API versioning strategy (from api-strategy.md)
5. **Blocks** deployment if critical breaking changes lack migration plan

The result: Zero unintentional breaking changes, smooth API evolution, maintained client trust.
</objective>

<quick_start>
<trigger_pattern>
Auto-trigger when detecting these modification patterns:

**API modifications**:
- "Remove endpoint", "Delete route", "Drop API"
- "Change request/response", "Modify payload", "Update schema"
- "Rename endpoint", "Change HTTP method"

**Database modifications**:
- "Drop column", "Remove field", "Delete table"
- "Change column type", "Modify constraint"
- "Rename column/table"

**Interface modifications**:
- "Change function signature", "Modify parameters"
- "Remove method", "Delete class"
- "Change return type"
</trigger_pattern>

<basic_workflow>
**Step 1**: Detect modification type
- User: "Remove the /api/v1/users endpoint"
- Detected: API endpoint deletion (BREAKING)

**Step 2**: Analyze breaking change risk
- Check: Is endpoint currently in use?
- Check: Are there clients depending on it?
- Check: What's the versioning strategy?

**Step 3**: Determine severity
- CRITICAL: Removing production endpoint with active users
- HIGH: Changing required field in request
- MEDIUM: Adding required parameter to function

**Step 4**: Suggest safe migration path
- **Option A**: Deprecate endpoint (mark for removal in v2.0)
- **Option B**: Version API (keep v1, add v2 without endpoint)
- **Option C**: Redirect to replacement endpoint

**Step 5**: Validate against api-strategy.md
- Check project's versioning policy
- Verify deprecation timeline
- Confirm backward compatibility requirements

**Step 6**: Block or warn
- CRITICAL → BLOCK implementation until migration plan approved
- HIGH → WARN and require justification
- MEDIUM → LOG for review
</basic_workflow>

<immediate_value>
**Without breaking-change-detector**:
```
Developer: "Let me remove this old /api/users endpoint"
*Removes endpoint*
*Deploys*
Result: 15 mobile apps break, support tickets flood in, emergency rollback
```

**With breaking-change-detector**:
```
Developer: "Let me remove this old /api/users endpoint"
Detector: "🚨 BREAKING CHANGE DETECTED

Removing: GET /api/users
Severity: CRITICAL
Impact: 15 active clients (iOS app, Android app, web dashboard)

This will break:
- Mobile app v2.1-2.5 (500K users)
- Partner integrations (3 companies)

Safe migration path:
1. Deprecate endpoint (add X-Deprecated header)
2. Announce removal timeline (90 days)
3. Monitor usage (track who's still calling it)
4. Version API (v2 without endpoint, v1 keeps it)
5. Remove after 90 days when usage drops to 0

Cannot proceed without migration plan. Would you like me to implement the deprecation strategy?"

Developer: "Yes, let's deprecate it properly"
Result: Smooth transition, zero broken clients, maintained trust
```
</immediate_value>
</quick_start>

<workflow>
<step number="1">
**Detect modification intent**

Parse user request to identify change type:

**API endpoint changes**:
- Removal: "remove", "delete", "drop" + "endpoint", "route", "API"
- Modification: "change", "update", "modify" + "request", "response", "payload"
- Renaming: "rename", "move" + "endpoint"

**Database schema changes**:
- Column removal: "drop", "remove" + "column", "field"
- Type changes: "change type", "alter column"
- Table changes: "drop table", "remove table"

**Interface/contract changes**:
- Function signature: "change signature", "modify parameters", "update return type"
- Method removal: "remove method", "delete function"
- Required fields: "make required", "add required"

See [references/change-detection-patterns.md](references/change-detection-patterns.md) for complete patterns.
</step>

<step number="2">
**Classify breaking change type**

Categorize the detected change:

**Type 1: Hard breaking changes** (always break clients):
- Removing endpoint
- Changing endpoint URL
- Changing HTTP method (GET → POST)
- Removing required field from response
- Adding required field to request
- Dropping database column
- Changing authentication scheme

**Type 2: Soft breaking changes** (may break some clients):
- Changing response field type
- Changing error codes
- Adding required query parameter
- Changing default behavior
- Modifying rate limits

**Type 3: Non-breaking changes** (safe):
- Adding optional field to request
- Adding new field to response
- Adding new endpoint
- Deprecating (but not removing) endpoint
- Making required field optional

See [references/breaking-change-taxonomy.md](references/breaking-change-taxonomy.md) for full classification.
</step>

<step number="3">
**Assess impact scope**

Determine who/what will be affected:

**For API changes**:
1. **Find endpoint usage**:
   - Grep codebase for endpoint URL
   - Check API logs for recent requests
   - Identify client applications (mobile app, web app, partners)

2. **Estimate client count**:
   - Internal clients (known)
   - External clients (unknown, but logged)
   - Partner integrations (contractual obligations)

3. **Determine criticality**:
   - Production traffic volume
   - Business-critical operations
   - SLA commitments

**For datab