rfc-review-compatibility - SKILL.md Agent Skill

name: rfc-review-compatibility description: Deep-dive review of a technical RFC focused on change-management concerns — API/ABI/wire/on-disk compatibility, version skew, migration tooling, rollout mechanics, reversibility, and consumer impact. Produces a written review report. Use when an RFC touches a stable surface (public API, plugin ABI, on-disk or wire format), or as a follow-up pass after `/rfc-review` flags compatibility as a deeper concern. argument-hint: "[]" allowed-tools: Read, Grep, Glob, Bash, WebFetch

RFC Review — Compatibility & Change-Management Deep Dive

Focused lens on a single RFC. Where the umbrella /rfc-review gives change management one paragraph among five, this skill spends the entire pass on it. A reader of the report should be able to answer:

If we ship this and an N-1 consumer hits the new code, what happens?
If we ship it and discover it's wrong tomorrow, what is the rollback?
Who depends on the surface we're changing, and have they been consulted?

Usage

/rfc-review-compatibility                       # Find the RFC on the current branch and review it
/rfc-review-compatibility docs/rfcs/my-rfc.md   # Review a specific RFC file

Can be invoked standalone, or as a follow-up when /rfc-review recommends a deeper compat pass.

When to invoke this skill

The RFC proposes a change to a stable surface: public API headers, plugin ABI, exported symbols, wire protocol, on-disk format, configuration schema.
The RFC introduces or modifies a shim, compatibility layer, or version-bridging code.
The RFC describes a deprecation, replacement, or migration of an existing feature.
The umbrella /rfc-review ran and flagged compatibility as the area needing a deeper pass.

Do NOT invoke for greenfield code with no existing consumers, or for pure internal refactors with no surface exposed to downstreams — the lens has nothing to bite on.

Workflow

Step 1 — Locate the RFC

In order of preference:

Argument path, if provided.
PR/branch context: git log -1 --name-only and look for added/modified .md files under docs/, rfcs/, design/, or paths matching *rfc*.
If still ambiguous, ask the user for the path. Do not guess across multiple candidates.

Step 2 — Read the RFC and surrounding surface

Read the full RFC end-to-end. Do not skim — compat issues hide in the parts that look like boilerplate.
Identify the surface(s) being changed: which headers, which exported symbols, which plugin entry points, which formats. Use Grep/Glob to confirm what currently exists.
Identify the current consumers of that surface where possible. For a shim, that means: who calls the old API today? For a plugin interface, who ships plugins against it?
Note the RFC's own claims about compatibility, migration, rollout, and reversibility — these are what you are evaluating.

Step 3 — Walk the focused checklist

See prompt.md for the full per-area checklist. The sub-areas:

Compatibility kinds — API, ABI, behavior, wire/on-disk format.
Version skew — client/server, plugin/host, build-time vs runtime.
Migration — tooling, deprecation timeline, communication.
Rollout — feature flags, staged rollout, dark-launch.
Reversibility — rollback story, forward-compat for the rollback.
Consumer/dependency impact — who is affected, have they been consulted.
Domain hooks — C++ ABI, plugin interface stability, CUDA/HIP/cuDNN-style API evolution.

For each sub-area produce: strengths (skip if none), concerns (graded blocking / non-blocking), questions for the author. A sub-area with nothing to say is one line — do not pad.

Step 4 — Ask the user how to deliver the report

Before writing, ask the user how they want the report delivered. Offer these options:

On disk next to the RFC — saved as <rfc-dir>/review-compat-<YYYY-MM-DD>-<reviewer>.md.
Inline in chat only — printed in the conversation, nothing written to disk.
Both — written to disk and printed inline.

Skip this prompt only if the user already stated a preference in the current turn (e.g. "just print it" or "save the review to ..."), in which case respect that and note the choice in your reply.

Step 5 — Synthesize the report

Use assets/templates/review-report.md as the structure. Lead with the verdict and blocking concerns; put per-area detail underneath.

If writing to disk, use the git user name (git config user.name) as <reviewer> and tell the user the path when done.

Step 6 — Recommend deeper passes

If the compat review surfaces concerns that need a different specialist (e.g. operational/build concerns, security/threat model), name them at the end of the report. This skill does not try to be the umbrella — it owns one lens deeply.

Output rules

No padding. A sub-area with nothing to say is one line: "Reversibility — no concerns." Do not invent issues.
Cite the RFC. Every concern references the specific section/line, so the author can find it.
Separate blocking from non-blocking. Blocking means "I would not approve without this resolved." Use sparingly.
Ask, don't assert. When a section is ambiguous, ask a question rather than critique a guess.
Verdict at the top. One of: approve, approve-with-comments, needs-revision, block. One-sentence justification.
Be specific to the surface. "ABI concerns" is not a finding; "adding a virtual method to cudnnHandle breaks vtable layout for existing plugins" is.

Examples

/rfc-review-compatibility
# → finds the RFC on the current branch, runs the compat deep dive

/rfc-review-compatibility docs/rfcs/0042-plugin-v2.md
# → reviews a specific RFC with the compat lens