breaking-change-detector

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/):

1. 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*.

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