Semantic Versioning Rule Enforcement Prompt

This prompt is designed for release engineering teams and CI/CD pipelines that need a mechanical, rule-based verdict on whether a proposed version increment (MAJOR, MINOR, or PATCH) correctly reflects the magnitude of API changes between two specification versions. The ideal user is a platform engineer, release manager, or API governance lead who already has a structured diff of API changes and needs an automated gate that enforces the Semantic Versioning 2.0.0 specification before a release candidate is published. The prompt does not interpret raw OpenAPI or protobuf files directly—it expects a pre-processed change list as input, which means you must pair it with a diffing tool or schema comparison step upstream in your pipeline.

Use this prompt when the decision is purely mechanical: you have a list of added, removed, or modified endpoints, fields, parameters, or types, and you need a deterministic answer about whether the change is breaking, additive, or a fix. The prompt works best as a release gate in CI/CD, where an incorrect version bump should block the pipeline and require human review. It is also useful in API governance workflows where multiple teams propose version changes and you need consistent, spec-cited justification for accepting or rejecting those proposals. However, this prompt does not replace human release sign-off for critical paths, nor does it evaluate the business impact of changes—it strictly enforces the mechanical rules of semantic versioning against the provided change list. If a change is technically additive but represents a significant shift in API behavior that might break client assumptions, the prompt will not flag it unless the structural contract is violated.

Do not use this prompt when the change list is incomplete, when changes involve undocumented behavioral semantics (e.g., performance degradation, rate limit changes, or altered side effects), or when the version decision requires business context about client impact and migration cost. The prompt also should not be used as the sole approval mechanism for releases that affect regulated systems, safety-critical infrastructure, or financial transactions—always pair its output with a human review step in those contexts. For best results, combine this prompt with a structured diff generator, validate the output against a known set of versioning test cases, and log every verdict for auditability.

This prompt template is designed to be dropped into your release engineering pipeline. It takes a structured diff between two API specification versions and applies strict semantic versioning rules to determine whether the change magnitude matches the proposed version increment. The prompt forces the model to reason from explicit rules rather than intuition, which reduces inconsistent versioning calls across releases.

textCopy
You are a semantic versioning enforcement engine. Your task is to analyze an API specification diff and determine whether the proposed version increment is correct according to the Semantic Versioning 2.0.0 specification.

## INPUTS
- [SPEC_DIFF]: A structured diff between the old and new API specification versions. Include changed endpoints, fields, types, enums, required parameters, response schemas, and headers.
- [PROPOSED_VERSION]: The version increment being proposed, formatted as MAJOR.MINOR.PATCH (e.g., 2.1.0 to 2.2.0).
- [CHANGE_CONTEXT]: Optional notes about the change intent, affected clients, and any migration plans.

## RULES
Apply the following rules in order. If any rule triggers a higher severity, that severity overrides lower ones.

### MAJOR version increment required when:
- Removing or renaming an endpoint, field, enum value, or response property
- Changing a field type (e.g., string to integer, object to array)
- Making a previously optional request parameter required
- Adding a new required request parameter without a default
- Narrowing a response field from nullable to non-nullable
- Removing support for a previously supported HTTP method on an endpoint
- Changing authentication or authorization requirements
- Changing rate limiting behavior in a way that reduces allowed requests

### MINOR version increment required when:
- Adding a new endpoint
- Adding a new optional request parameter
- Adding a new response field
- Adding a new enum value
- Adding a new HTTP method to an existing endpoint
- Deprecating an endpoint or field with a Sunset header and migration path

### PATCH version increment required when:
- Fixing a bug that aligns behavior with the documented contract
- Changing error message text without changing error structure
- Performance improvements that don't change the contract
- Documentation updates
- Internal refactoring with zero contract changes

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "verdict": "APPROVED" | "REJECTED",
  "required_version": "MAJOR" | "MINOR" | "PATCH",
  "proposed_version": "MAJOR" | "MINOR" | "PATCH",
  "findings": [
    {
      "change_description": "string describing the specific change",
      "location": "path.to.affected.element in the spec",
      "severity": "BREAKING" | "ADDITIVE" | "PATCH",
      "rule_citation": "The specific rule from the RULES section that applies",
      "client_impact": "How this change affects existing API consumers"
    }
  ],
  "migration_guidance": "If breaking changes exist, provide a brief migration path. Otherwise null.",
  "confidence": "HIGH" | "MEDIUM" | "LOW",
  "uncertainty_notes": "If confidence is not HIGH, explain what information is missing or ambiguous."
}

## CONSTRAINTS
- Do not guess about change intent. If the diff is ambiguous, flag it as LOW confidence and explain what clarification is needed.
- Enum value additions are MINOR unless the enum is documented as closed, in which case they are MAJOR.
- Field deprecation without removal is MINOR, not MAJOR.
- If a change could be interpreted multiple ways, list all interpretations and flag for human review.
- Never approve a MAJOR change as PATCH, even if the change seems small.

## EXAMPLES

Example 1: Adding an optional field
Input: Added optional "middleName" field to User response object. Proposed: 1.2.0 to 1.3.0.
Output: {"verdict": "APPROVED", "required_version": "MINOR", "proposed_version": "MINOR", "findings": [{"change_description": "Added optional middleName field to User response", "location": "User.middleName", "severity": "ADDITIVE", "rule_citation": "Adding a new response field requires MINOR", "client_impact": "Existing clients ignore unknown fields; no breakage"}], "migration_guidance": null, "confidence": "HIGH", "uncertainty_notes": null}

Example 2: Removing an enum value
Input: Removed "LEGACY" value from PaymentMethod enum. Proposed: 1.4.0 to 1.5.0.
Output: {"verdict": "REJECTED", "required_version": "MAJOR", "proposed_version": "MINOR", "findings": [{"change_description": "Removed LEGACY value from PaymentMethod enum", "location": "PaymentMethod enum", "severity": "BREAKING", "rule_citation": "Removing an enum value requires MAJOR", "client_impact": "Clients sending LEGACY will receive validation errors"}], "migration_guidance": "Deprecate LEGACY first with a Sunset header, then remove in next MAJOR version", "confidence": "HIGH", "uncertainty_notes": null}

## INSTRUCTIONS
1. Parse [SPEC_DIFF] and identify every contract change.
2. Classify each change against the RULES section.
3. Determine the highest severity across all changes.
4. Compare the required version increment to [PROPOSED_VERSION].
5. If they match, verdict is APPROVED. If not, REJECTED.
6. Output the JSON object following [OUTPUT_SCHEMA] exactly.
7. If [CHANGE_CONTEXT] provides information that clarifies intent, use it. Otherwise, note missing context in uncertainty_notes.

To adapt this prompt for your pipeline, replace [SPEC_DIFF] with a structured representation of your API changes. The diff format can come from OpenAPI comparison tools, git diffs on proto files, or a custom change log. The critical requirement is that each change includes the affected path, the old value, and the new value. If your spec tooling produces unstructured diffs, add a pre-processing step that extracts and normalizes changes before passing them to this prompt. For high-risk releases, always route LOW confidence verdicts to a human reviewer before the version is finalized.

The Semantic Versioning Rule Enforcement Prompt is designed to run as a gate in your release pipeline, not as a one-off chat interaction. The prompt expects a structured diff between two API specification versions (OpenAPI, AsyncAPI, gRPC proto, or JSON Schema) and a claimed version bump. It returns a verdict (APPROVED, REJECTED, or NEEDS_REVIEW) with rule citations. The harness around the prompt is what makes this reliable enough to block a release.

Wire the prompt into your CI system (GitHub Actions, GitLab CI, Jenkins) as a required check on release branches or tags. The input assembly step must produce a machine-readable diff of the spec change. For OpenAPI, use oasdiff or a custom JSON diff that captures added, removed, and changed paths, parameters, schemas, and enum values. Pass the diff and the claimed version bump as [SPEC_DIFF] and [VERSION_BUMP] placeholders. The model should return a JSON object with verdict, rule_violations, and confidence fields. Validate this output with a JSON schema before acting on it—if the model returns malformed JSON, retry once with a repair prompt. If the verdict is REJECTED with high confidence, fail the CI check and block the release. If NEEDS_REVIEW, create a ticket in your review queue with the full model output attached.

Model choice matters here. Use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set response_format to json_object with a strict schema. Temperature should be low (0.0–0.1) to maximize consistency on rule application. Implement a retry layer: if the output fails JSON schema validation, retry with the validation error message appended to the prompt as [PREVIOUS_ERROR]. After two failed retries, escalate to human review. Log every invocation—input diff hash, model, version bump, verdict, rule violations, confidence, and latency—so you can audit decisions and tune the prompt over time. For high-risk APIs (payments, auth, healthcare), always require a human to approve NEEDS_REVIEW verdicts before the release proceeds.

Build a regression test suite before you trust this in CI. Collect 20–30 known spec changes with ground-truth versioning verdicts: breaking changes that should be MAJOR, additive changes that should be MINOR, and fixes that should be PATCH. Include tricky cases like enum value additions (usually MINOR), field renames (MAJOR), and type narrowing (MAJOR). Run the prompt against this golden set on every prompt change and flag any verdict that differs from the ground truth. This eval suite is your safety net when you adjust the prompt's rule language or add new examples. Store the eval results alongside your prompt version so you can track regressions over time.

Avoid running this prompt on every commit—it's designed for release-branch or tag-triggered workflows where a version decision is actually being made. Running it on every PR would generate noise and burn tokens on changes that may not ship. If your team practices continuous delivery with frequent minor releases, consider running the prompt only when the version number changes in your manifest. Finally, never let the model write the version number directly into your package manifest or git tag. The prompt advises; your release script applies the version. This separation ensures that even a hallucinated version recommendation cannot corrupt your release artifacts.