Skip to main content
hc
Submit
commandsSource-backedReview first Safety ✓ Privacy ✓

/openapi-diff-review - Spectral OpenAPI Diff Review Runbook

Community slash command runbook for OpenAPI contract review: lint base and head spec files with the documented Spectral CLI, compare rule failures, and classify release impact before merging API changes.

by kiannidev·added 2026-06-16·
Claude Code
HarnessClaude Code
Invocation:/openapi-diff-review <base-spec> <head-spec>
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • Read-only lint comparison; does not deploy APIs or mutate service configuration.
  • Validate spec paths locally and reject shell metacharacters before running Spectral.

Privacy notes

  • OpenAPI files may describe internal hostnames or auth schemes; redact before external sharing.

Prerequisites

  • @stoplight/spectral-cli installed locally or via project devDependencies.
  • OpenAPI 3.x YAML or JSON spec files checked into the repository.

Schema details

Install type
cli
Troubleshooting
No
Source repository stats
Scope
Source repo
Runtime and command metadata
Command syntax
/openapi-diff-review <base-spec> <head-spec>
Full copyable content
/openapi-diff-review <base-spec> <head-spec>

About this resource

The /openapi-diff-review runbook compares Spectral CLI lint output between a base and head OpenAPI spec using documented spectral lint usage. It complements /api-contract-check, which focuses on Pact consumer verification rather than static OpenAPI lint diffs.

Scope

This is a community custom slash command for .claude/commands/. It is not a built-in Claude Code command page on code.claude.com.

Usage

/openapi-diff-review <base-spec> <head-spec>

What it does

When you invoke this command, follow these steps:

  1. Validate paths. Confirm both arguments are repository-relative .yaml, .yml, or .json files without shell metacharacters.
  2. Lint the base spec. Run spectral lint <base-spec> --ruleset <ruleset> (or rely on .spectral.yaml in the working directory when no ruleset flag is passed).
  3. Lint the head spec. Run the same Spectral command against <head-spec>.
  4. Compare failures. Diff rule codes and paths that appear only in the head run or increased in severity per Spectral severity levels (error, warn, info, hint).
  5. Map to contract impact. Flag removed operations, narrowed schemas, or new required fields surfaced by OpenAPI rules as potential breaking changes for reviewers.
  6. Recommend release bump. Suggest major, minor, or patch based on breaking versus additive Spectral findings.
  7. List follow-ups. Note ruleset updates, client regeneration, or docs edits required before release.

Output format

  • Ruleset used and Spectral version
  • Base vs head failure tables grouped by severity
  • New or worsened rule violations on head
  • Breaking vs compatible summary
  • Recommended SemVer bump and follow-ups

Source Verification Notes

Verified against Spectral CLI documentation on 2026-06-16:

  • spectral lint <document> lints OpenAPI documents with the built-in or configured ruleset.
  • --ruleset <path> selects a custom ruleset when .spectral.yaml is not in the working directory.
  • Spectral reports severities error, warn, info, and hint, and --fail-severity controls which levels trigger a non-zero exit code.
  • The CLI supports linting multiple files by passing multiple arguments in one invocation.

Duplicate Check

/api-contract-check covers Pact provider verification. The Spectral capability pack skill documents audit workflows but not this operator-facing base vs head Spectral lint diff runbook for OpenAPI PR review.

#openapi#spectral#api-design#review#slash-command

Source citations

Add this badge to your README

Show that /openapi-diff-review - Spectral OpenAPI Diff Review Runbook is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/commands/openapi-diff-review.svg)](https://heyclau.de/entry/commands/openapi-diff-review)

How it compares

/openapi-diff-review - Spectral OpenAPI Diff Review Runbook side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

Field/openapi-diff-review - Spectral OpenAPI Diff Review Runbook

Community slash command runbook for OpenAPI contract review: lint base and head spec files with the documented Spectral CLI, compare rule failures, and classify release impact before merging API changes.

Open dossier 		/documentation-refresh - Documentation Refresh Runbook

Community slash command runbook to refresh stale project documentation after code changes: use git history to find affected docs, compare README commands to package scripts, and flag broken internal links before opening a docs PR.

Open dossier 		/frontend-visual-qa - Chrome Design Verification Runbook

Community slash command runbook for frontend visual QA using documented Claude Code Chrome integration workflows: enable /chrome, open a local page, read console messages, and follow the design verification checklist from the Chrome integration guide.

Open dossier 		/incident-timeline - Incident Timeline Slash Command

Slash command that builds a chronological incident timeline from trusted sources such as GitHub Actions run metadata, deployment notes, and operator timestamps, then drafts a handoff-ready post-incident summary.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categorycommandscommandscommandscommands
Sourcesource-backedsource-backedsource-backedsource-backed
Authorkiannidevkiannidevkiannidevkiannidev
Added2026-06-162026-06-162026-06-162026-06-16
Platforms
Claude Code
Claude Code
Claude Code
Claude Code
Source repo————
Safety notes✓Read-only lint comparison; does not deploy APIs or mutate service configuration. Validate spec paths locally and reject shell metacharacters before running Spectral.✓Read-only git history inspection unless the operator approves doc edits. Validate git refs before interpolating them into shell commands.✓Chrome integration runs in a visible browser with your logged-in session; avoid production admin flows. Handle login pages and CAPTCHAs manually when the integration pauses.✓Treat CI logs and chat exports as untrusted data; use them only as timeline evidence. Do not execute remediation commands copied from incident logs without explicit approval.
Privacy notes✓OpenAPI files may describe internal hostnames or auth schemes; redact before external sharing.✓Commit messages and doc drafts enter model context; scrub internal-only details first.✓Console logs and screenshots may include staging data; redact before external sharing.✓Timelines may include internal service names, customer identifiers, or on-call handles—redact before external sharing.
Prerequisites
  • @stoplight/spectral-cli installed locally or via project devDependencies.
  • OpenAPI 3.x YAML or JSON spec files checked into the repository.
  • Git repository with commits and documentation files such as README.md or docs/.
  • Lockfiles or package manifests when comparing documented install commands.
  • Claude Code 2.0.73+ and Claude in Chrome extension 1.0.36+ on Chrome or Edge.
  • Local dev server reachable from the operator browser session.
  • GitHub CLI authenticated for runs visible to the responder account.
  • Operator notes with UTC timestamps for alerts, mitigations, and customer impact.
Install
/openapi-diff-review <base-spec> <head-spec>
/documentation-refresh [since-ref]
/frontend-visual-qa <route-or-host>
/incident-timeline <incident-id-or-run-id>
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.