breaking-change-detector

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.

<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>

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"