OpenAPI Breaking Change Audit

## Purpose

Detect breaking changes in OpenAPI (Swagger) specifications by comparing the current spec against its previous revision. Catch removals, type changes, and constraint tightenings that would break existing API consumers.

## Trigger

Activate when a developer modifies an OpenAPI spec file (openapi.yaml, openapi.json, swagger.yaml, swagger.json) or asks about API compatibility.

## Analysis steps

Step 1, Identify the change scope:
- Determine which paths, operations, parameters, request bodies, and response schemas were added, modified, or removed.
- Additions are safe by default. Focus analysis on modifications and removals.

Step 2, Check for endpoint removals:
- A removed path or HTTP method is always a breaking change.
- A path that changed its pattern (e.g., /users/{id} became /users/{userId}) is a breaking change even if semantically equivalent, because client code generates parameter names from the spec.
- A deprecated endpoint that is now removed: verify the deprecation was announced for at least one release cycle.

Step 3, Check for parameter breaking changes:
- A required parameter added to an existing operation is breaking. Clients that do not send it will get 400 errors.
- A parameter renamed or moved (query to header, path to query) is breaking.
- A parameter type narrowed (string to enum, number to integer) is breaking.
- A parameter default value removed is breaking if clients relied on the server default.
- An optional parameter becoming required is breaking.

Step 4, Check for request body breaking changes:
- A required property added to a request schema is breaking.
- A property type changed (string to number, object to array) is breaking.
- A property removed from the schema is safe for requests (server ignores it) but flag it as a Warning because client code may still reference it in generated SDKs.
- An enum value removed from a request property is breaking if clients send that value.
- A maxLength, minimum, maximum, or pattern constraint tightened is breaking. Values that previously passed validation will now fail.

Step 5, Check for response body breaking changes:
- A property removed from a response schema is breaking. Clients that read it will get undefined or null.
- A property type changed in a response is breaking.
- A new required property added to a response is safe (additive).
- An enum value added to a response property is potentially breaking for clients that exhaustively match on enum values. Flag as Warning.
- A nullable property becoming non-nullable is safe. A non-nullable property becoming nullable is breaking for clients that do not handle null.

Step 6, Check for status code and content type changes:
- A success status code changed (200 to 201, or 200 to 204) is breaking for clients that check status codes.
- A content type removed (application/json removed, only application/xml remains) is breaking.
- A new error status code added is safe but flag as Suggestion so client error handling can be updated.

Step 7, Check for authentication and security scheme changes:
- A security requirement added to a previously unauthenticated endpoint is breaking.
- A security scheme type changed (apiKey to oauth2) is breaking.
- An OAuth scope added to an existing endpoint is breaking for clients with limited scope grants.

## Output format

For each finding, report:

Location: the path, operation, and specific schema property or parameter.
Change type: Removal, Type change, Constraint tightening, New requirement, Rename, Security change.
Severity: Critical if it will cause client errors immediately on deployment. Warning if it will cause issues in generated SDKs or edge cases. Suggestion if it is additive but clients should be aware.
Impact: one sentence describing what breaks for existing consumers.
Mitigation: one sentence describing how to make the change non-breaking (versioning, deprecation period, default value, optional flag).

Sort findings by severity, Critical first.

End with a summary: total breaking changes found, recommended action (safe to ship, ship with deprecation notice, requires new API version).

## Constraints

- Compare only what is in the spec. Do not assume server behavior beyond what the spec declares.
- Treat OpenAPI 3.0 and 3.1 differences in nullable handling correctly. In 3.0, nullable is a separate keyword. In 3.1, null is a type in a type array.
- If only one version of the spec is provided, review it for internal consistency issues that would become breaking changes if any marked-deprecated elements are removed. State that a diff requires the previous revision.
- Do not suggest downgrading the OpenAPI version.
- When a change is breaking, always provide a non-breaking alternative. Prefer additive evolution (new optional fields, new endpoints) over modification of existing contracts.