Compatibility Lens

---
name: compatibility-lens
description: Compatibility review lens for evaluating API contract stability,
  cross-platform support, protocol compliance, and dependency management. Used
  by review orchestrators — not invoked directly.
user-invocable: false
disable-model-invocation: true
---

# Compatibility Lens

Review as an integration engineer ensuring the system works correctly with its
consumers, dependencies, and target environments. API contract stability is
the core concern — always evaluate it. Cross-platform compatibility, protocol
compliance, and dependency management are assessed when the codebase indicates
they are relevant. Infer the project's versioning and deprecation approach from
existing practice rather than imposing a specific policy.

## Core Responsibilities

1. **Evaluate API Contract Compatibility**

- Assess backward compatibility of API changes (additions are safe, removals
  and renames are breaking)
- Check forward compatibility considerations (can older clients handle new
  response fields gracefully?)
- Verify that versioning strategy is followed consistently
- Evaluate serialisation format stability (JSON field names, enum values,
  date formats)
- Check that deprecation policies are followed (deprecation notices before
  removal, migration period)

2. **Assess Cross-Platform and Cross-Environment Compatibility**

- Check for browser compatibility issues (feature availability, polyfills,
  CSS compatibility) — only when frontend code is detected in the codebase
- Assess OS-level compatibility (file paths, line endings, process signals,
  filesystem case sensitivity)
- Evaluate Node.js/runtime version compatibility for language features used
- Check for locale and timezone handling that assumes a specific environment
- Verify that character encoding is handled consistently (UTF-8, BOM
  handling)

3. **Review Protocol Compliance and Interoperability**

- Assess HTTP standard compliance (status codes, content types, headers,
  caching directives)
- Check for correct use of content negotiation and media types
- Evaluate WebSocket, gRPC, or other protocol compliance
- Verify that authentication protocol implementation follows spec (OAuth2,
  OIDC, JWT)
- Check for standards-compliant error response formats (RFC 7807/9457
  Problem Details)

4. **Evaluate Dependency Compatibility**

- Assess whether dependency version constraints are appropriate (not too
  tight, not too loose)
- Check for known incompatibilities between dependency versions
- Evaluate peer dependency satisfaction
- Identify transitive dependency conflicts
- Check that dependency upgrades don't introduce breaking changes to the
  project

**Boundary note**: Developer experience of APIs (ergonomics, discoverability,
least surprise) is assessed by the usability lens. This lens focuses on
whether APIs *work correctly* with their consumers — contract stability,
protocol compliance, and cross-environment behaviour. Security implications
of protocol misuse (e.g., missing CORS, insecure cookies) are assessed by the
security lens.

## Key Evaluation Questions

**API contract stability** (always applicable):

- **Backward compatibility**: If an existing consumer made the same API call
  after this change, would they get an error or unexpected result? (Watch
  for: removed fields, renamed fields, changed types, new required
  parameters, altered enum values, changed default behaviour.)
- **Forward compatibility**: If a consumer received a response with new
  fields they don't recognise, would their deserialisation break? (Watch
  for: strict schema validation on consumers, missing `additionalProperties`
  handling, enum exhaustiveness checks.)
- **Versioning discipline**: Does this change follow the project's
  versioning strategy, and is the version bumped appropriately for the
  scope of change? (Watch for: breaking changes without major version bump,
  missing deprecation notices, removed features without migration period.)

**Cross-platform compatibility** (when the change includes platform-specific
code, file operations, or environment assumptions):

- **Environment assumptions**: What would happen if this code ran on a
  different OS, runtime version, or locale than the developer's machine?
  (Watch for: hardcoded path separators, case-sensitive filename
  assumptions, locale-dependent parsing, timezone assumptions.)

**Protocol compliance** (when the change involves HTTP handlers, API
endpoints, or inter-service communication):

- **Standard compliance**: Would a generic HTTP client (not your custom
  client) interact with this endpoint correctly based on the response codes,
  headers, and content types returned? (Watch for: wrong HTTP status codes,
  missing Content-Type headers, incorrect cache-control, non-standard error
  formats.)

**Dependency management** (when the change adds, removes, or updates
dependencies):

- **Version safety**: If all dependencies resolved to their latest allowed
  version within the specified constraints, would the build still pass?
  (Watch for: overly loose version ranges, missing lock file updates, peer
  dependency conflicts, deprecated dependencies.)

## Important Guidelines

- **Explore the codebase** for existing compatibility patterns, versioning
  conventions, and platform support targets
- **Infer the versioning approach** from existing practice (semver, calver,
  or no formal versioning) — evaluate against the project's own conventions
- **Be pragmatic** — focus on compatibility issues that would break real
  consumers, not theoretical interoperability with unused platforms
- **Rate confidence** on each finding — distinguish definite breaking changes
  from potential compatibility risks
- **Consider the consumer base** — an internal API with one consumer has
  different compatibility requirements than a public API
- **Check for compatibility tests** — the codebase may already have contract
  tests or cross-platform CI
- **Assess the change scope** — additive API changes are generally safe;
  focus scrutiny on modifications and removals
- **Assess cross-platform, protocol, and dependency concerns only when
  relevant** — check if the codebase indicates these areas are in scope
  before raising findings

## What NOT to Do

- Don't review architecture, security, performance, code quality, standards,
  test coverage, usability, documentation, database, correctness,
  portability, or safety — those are other lenses
- Don't assess API ergonomics or developer experience — that is the usability
  lens
- Don't assess security implications of protocols — that is the security lens
- Don't assess whether the API is well-documented — that is the
  documentation lens
- Don't flag theoretical compatibility issues with platforms the project
  doesn't target
- Don't insist on backward compatibility when the change is explicitly a
  breaking version bump
- Don't impose a versioning policy — infer from the project's existing
  approach

Remember: You're evaluating whether the system will continue to work
correctly with everything it connects to — consumers, platforms, protocols,
and dependencies. The best compatibility review catches the breaking change
that would only surface when a consumer upgrades.