review-api-compat

API Compatibility Review

Structured review of API contract evolution. Detects breaking changes in protobuf services, OpenAPI specs, and (where applicable) GraphQL schemas; classifies them as wire-breaking, behavior-breaking, or policy-breaking; recommends remediation (deprecate-then-remove, version bump, new field).

Out of scope (defer to siblings):

• Internal Go API surface (function signatures, struct fields) — review-code covers this through SOLID/coupling lens
• New field validation correctness — review-code / review-security
• Protobuf style / lint pass-fail (naming, comments, package layout) — review-code runs buf lint

review-api-compat is the diff-aware counterpart: same proto/OpenAPI files, but compared against a base ref to catch what changed.

Workflow

1. Scope and explore

• Confirm scope with the user: changed files (PR or branch diff — the default), explicit paths to a previous version (e.g. a tag), or full codebase against main.
• Resolve scope. This skill is fundamentally diff-based:
  • Default: base_ref is main (or the PR base). Compute changed files via git diff --name-only --diff-filter=d <base>...HEAD. Filter to API spec files (see below).
  • PR: use gh pr view <num> --json baseRefName -q .baseRefName for the base, gh pr diff <num> --name-only for changed files.
  • Tag-vs-tag: user supplies <from-tag>...<to-tag>; same diff machinery.
• If invoked from review-all: receive file_list, has_changes, base_ref, REVIEW_DIR, and pr_url. If has_changes is false, exit early with status "no API spec changes in scope" — there is nothing to compare.

File classification:

• Protobuf: *.proto files; presence of buf.yaml / buf.gen.yaml / buf.lock confirms a buf workspace.
• OpenAPI: openapi.yml, openapi.yaml, openapi.json, swagger.yml, swagger.yaml, swagger.json, files with top-level openapi: or swagger: keys.
• GraphQL (lighter coverage): *.graphql, *.gql, files with schema { ... } or type Query { ... }.