# Semver Cop

> Determine whether the next release is legally a patch, minor, or major by diffing the public API surface against the last published version. Use before cutting a release, when reviewing "is this breaking?", or when writing honest release notes.

- Skill: `tokyubevoxelverse/semver-cop` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tokyubevoxelverse/semver-cop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tokyubevoxelverse/semver-cop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tokyubevoxelverse (https://skillmd.com/u/tokyubevoxelverse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tokyubevoxelverse/semver-cop

---


# Semver-cop

Semver is a legal system: the version number is a contract about what consumers can upgrade to blindly. Your job is to rule on the next release — patch, minor, or major — by *diffing the actual public surface*, not by skimming the changelog. Downgrading a breaking change to a minor is the crime; upgrading a patch to a major out of paranoia is just bad style. Rule precisely.

## Phase 1 — Establish the two surfaces

- Find the last released version: registry (`npm view`, PyPI, crates.io) first, tags second; if they disagree, the registry is what consumers have — flag the drift.
- Check out the released version in a **separate worktree**. Never diff against "main from around then."
- Extract the **public surface** at both points, ecosystem-appropriate: exported symbols and their signatures, public types/interfaces and their fields, config options and their defaults, CLI commands/flags/exit codes, HTTP routes and payload shapes, error types consumers can catch. Type definition files, `__all__`, docs, and explicit export lists define "public"; note where the boundary is only conventional (underscore prefixes) and apply the *ecosystem's* convention, not your own.

## Phase 2 — Classify every difference

For each change to the surface:

- **MAJOR** — removal or rename of anything public; signature narrowing (new required param, removed overload, narrowed input type); widened return/output type consumers must now handle; changed default that changes behavior; raised runtime/platform floor; error type or exit-code changes consumers may match on.
- **MINOR** — new exports, new optional params, widened *accepted* inputs, new config options with behavior-preserving defaults.
- **PATCH** — no surface change (but see behavior, below).

**The signature-invisible break:** for exported functions whose *bodies* changed, scan the diff for changed return shapes, newly thrown/removed errors, changed side effects, and meaningful output-format changes (if the CLI's stdout is parseable, its format is public surface). A bugfix that consumers depend on (Hyrum's law) is technically PATCH — but call out high-blast-radius behavior fixes so the release notes can warn.

## Phase 3 — The ruling

1. **The verdict:** the minimum legal next version, stated plainly.
2. **The evidence:** every MAJOR item (exact symbol, old vs. new, why it breaks a consumer — with a one-line hypothetical consumer that would break), then MINOR items, then notable PATCH-level behavior changes.
3. **The escape review:** for each MAJOR item, whether a compatibility shim (deprecated alias, overload retained, default preserved behind an option) could legally demote the release to MINOR — with the shim sketched. Sometimes shipping the shim is an hour and skipping the major saves every consumer a migration.
4. **Release-notes draft:** breaking changes first, each with its one-line migration instruction.

## Rules

- Undocumented-but-exported is still public unless the ecosystem's convention clearly marks it internal.
- "Nobody uses that" is not a classification argument; it's a risk note.
- Be honest about limits: this analysis reads surfaces and diffs — deep behavioral equivalence isn't provable this way, and the report says which parts rest on body-diff heuristics.