protobuf-grpc-api-review - Claude MCP Skill

# Protobuf and gRPC API Review

Review `.proto` and related gRPC changes as long-lived contracts. Distinguish what the wire format permits from what generated clients, JSON users, stored data, and mixed-version deployments can safely tolerate.

## Start With the Compatibility Envelope

Before deciding whether a change is safe, determine:

- the old and new schema, not only the final file
- whether payloads use binary protobuf, ProtoJSON, text format, or more than one encoding
- whether messages persist in databases, queues, logs, caches, or events
- whether clients exist outside the repository or release independently
- the protobuf syntax or edition and the generated languages/runtime versions
- whether HTTP/JSON transcoding, reflection, service config, or schema registries expose the contract
- the deployment order, rollback window, and duration of mixed-version operation

If context is missing, state the assumption and lower confidence. Do not call a change backward-compatible from the new schema alone.

## Review Workflow

### 1. Inventory Contract Changes

Compare the old and new definitions by fully qualified symbol. Record:

- message fields: number, name, type, cardinality, presence, `oneof`, defaults, and relevant options
- enums: value name, number, aliases, reservations, and zero value
- services: package, service, method, request and response types, and streaming mode
- generated API inputs: package options, outer class names, namespaces, and custom options

Ignore formatting-only changes after confirming they do not alter descriptors or generated APIs.

### 2. Evaluate Four Compatibility Dimensions

Assess each affected symbol independently:

1. **Binary wire** — can old and new readers parse both old and new bytes without corruption or loss?
2. **Named formats** — do ProtoJSON, text-format, REST-transcoded, or name-based consumers still work?
3. **Source and generated API** — will regenerated clients compile and preserve presence, enum, and accessor behavior?
4. **Behavior and operations** — do status codes, retry safety, deadlines, authorization, streaming, and resource bounds preserve the RPC contract?

Read [protobuf compatibility rules](references/protobuf-compatibility.md) for field, enum, presence, `oneof`, and serialization changes. Read [gRPC contract review](references/grpc-contract-review.md) when services, methods, or runtime behavior change.

### 3. Trace Mixed-Version Scenarios

For every non-trivial change, reason through these paths:

- old writer -> new reader
- new writer -> old reader
- old reader modifies and reserializes a new message
- rollback after new writers have emitted new values
- persisted old data read after the migration

For conditionally compatible changes, identify the exact writer constraint and the point at which it may be relaxed. A safe rollout commonly requires deploying readers before writers and retaining the old field or method until rollback is no longer needed.

### 4. Review Repository Evidence

Use the repository's own tooling when available:

- compile descriptors with the project's `protoc`, Buf, Gradle, Maven, Bazel, or language-specific task
- run configured breaking-change or lint checks
- inspect generated-code diffs only when they are committed by repository convention
- search call sites for exhaustive enum switches, presence assumptions, JSON field names, method paths, status handling, and retry configuration
- look for compatibility fixtures or descriptor baselines before proposing a new mechanism

Do not claim a check passed unless you ran it. If a required tool or baseline is unavailable, name the unverified risk.

### 5. Produce an Actionable Review

Lead with one verdict:

- **Compatible** — safe within the stated compatibility envelope
- **Rollout-dependent** — parseable, but safe only with explicit sequencing or value constraints
- **Breaking** — causes wire, named-format, source, or behavioral incompatibility
- **Insufficient context** — the old schema, encoding, consumers, or deployment model is unknown

Then provide only evidence-backed findings. For each finding include:

```text
[severity] Short title
Location: file and symbol or changed lines
Dimension: binary | JSON/text | source | behavior/operations
Change: old contract -> new contract
Impact: concrete failing mixed-version scenario
Remediation: smallest safe schema change or staged migration
```

Use **blocker** for corruption, unparsable data, tag reuse, or an unavoidable production break; **high** for likely cross-version data loss or unsafe RPC behavior; **medium** for bounded compatibility or operability risks; and **low** for maintainability issues that do not break the contract. Do not inflate style preferences into compatibility findings.

Conclude with:

- a compact compatibility matrix for changed symbols
- the rollout/rollback sequence if migration is required
- targeted tests that would prove the remaining assumptions

## Default Safety Principles

- Never reuse a field or enum number, even after deletion; reserve deleted numbers and usually names.
- Treat field-number changes and moving fields into an existing `oneof` as breaking.
- Treat type and cardinality changes as migrations, even when their binary wire types are compatible.
- Remember that adding a field or enum value can still break generated code or exhaustive consumers.
- Review ProtoJSON separately: names and unknown-field behavior make its compatibility envelope narrower than binary protobuf.
- Preserve unknown fields through read-modify-write paths when forward compatibility depends on them.
- Prefer additive evolution: add a new field or RPC, migrate readers and writers, deprecate the old contract, then remove it only after the compatibility window closes.
- Never recommend retries for a state-changing RPC without establishing idempotency or a deduplication mechanism.
- Require realistic client deadlines and cancellation-aware server work for production RPCs.

## Avoid False Positives

- Do not require every service to use streaming, retries, health checks, or HTTP transcoding.
- Do not flag a new optional field as breaking solely because old clients ignore it.
- Do not call a wire-compatible type change safe without checking value ranges and rollout order.
- Do not assume a renamed field is harmless when JSON, text format, reflection, or generated source APIs are consumers.
- Do not demand reservations for fields that never shipped; ask for release history when that distinction matters.