| name | breaking-change-detector |
| description | Compares two OpenAPI/API specification versions (V1 vs V2) to detect breaking changes and backward compatibility issues. |
Breaking Change Detector Protocol
This skill acts as the API gatekeeper. It prevents accidental deployment of changes that would break existing mobile apps, web clients, or 3rd-party integrations by comparing API contracts offline.
Core assumption: Once an API is published, you no longer control the clients. Removing a field or changing its type will cause production crashes.
1. Specification Diff Analysis (Static)
Compare Version A (Current) with Version B (Proposed) and categorize changes based on backward compatibility logic:
🔴 MAJOR: Breaking Changes (Requires v2 or /v2/ route)
- Removing an endpoint or method.
- Removing a property from a response payload.
- Changing a property data type (e.g.,
id from integer to uuid string).
- Adding a new required field to a request payload.
- Changing authentication requirements (e.g., enforcing scopes that weren't there).
🟡 MINOR: Non-Breaking Additions
- Adding a new optional field to a request payload.
- Adding a new property to a response payload (properly written clients ignore unknown fields).
- Adding a new endpoint.
🟢 PATCH: Fixes
- Fixing typos in documentation/descriptions.
- Changing examples.
2. Migration Guidance
If a breaking change is detected, immediately propose an alternative backward-compatible method or generate a migration guide for the clients.
3. Output Generation
Required Outputs (Must write BOTH to docs/api-report/):
- Human-Readable Markdown (
docs/api-report/breaking-change-report.md)
### 🚨 API Version Diff Assessment
- **Status:** FAILED / BREAKING DETECTED
- **Recommended SemVer:** MAJOR BUMP (`v1.4.0` -> `v2.0.0`)
#### 🔴 Breaking Changes
1. **Endpoint `GET /users/{id}`:** Response type of `status` changed from `boolean` to `string (enum)`. This will crash strongly-typed clients (like Swift/Kotlin).
2. **Endpoint `POST /orders`:** Added new **required** field `shipping_address`. Existing clients will start receiving `400 Bad Request`.
#### 💡 Migration / Remediation Strategy
- **Fix for POST /orders:** Make `shipping_address` optional in the database, or provide a default fallback on the server.
- **Fix for GET /users:** Create a new field `status_text` and leave `status` as a boolean, marked as *deprecated*.
- Machine-Readable JSON (
docs/api-report/breaking-change-output.json)
{
"skill": "breaking-change-detector",
"has_breaking_changes": true,
"recommended_bump": "MAJOR",
"breaking_changes": [
{"type": "response_type_change", "path": "/users/{id}", "field": "status", "old": "boolean", "new": "string"},
{"type": "required_field_added", "path": "/orders", "field": "shipping_address"}
]
}
Guardrails
- Ignore Order: The order of keys in JSON or OpenAPI specs does not constitute a breaking change.
- Query Params: Adding a required query parameter is breaking. Adding an optional one is not.
- Semantic Versioning Strictness: An API bump only follows SemVer rules for the public interface, not backend logic.
