Semantic Versioning Compliance Check Prompt

This prompt is for release engineers and API platform teams who need an automated, auditable gate in their CI/CD pipeline to validate that a proposed version bump—major, minor, or patch—correctly follows semantic versioning rules. The job-to-be-done is compliance verification: given a structured diff of schema changes between two API specification versions and a proposed new version, the prompt produces a compliance report that maps each change to the semver rule it triggers, provides a justification, and delivers a final pass/fail verdict. The ideal user is someone who already has a machine-readable diff of their API schemas (OpenAPI, GraphQL, or gRPC) and needs a deterministic, rule-based assessment before cutting a release, not a human reading a changelog.

To use this prompt effectively, you must provide a structured diff as input—a list of change objects that include the affected path, the change type (e.g., 'field_added_required', 'type_changed', 'endpoint_removed'), and the before/after values. The prompt also requires the proposed version string (e.g., '2.1.0') and a reference to the semver rules you want enforced (typically the semver 2.0.0 specification). The output is a JSON report with a verdict field ('compliant' or 'non-compliant'), a rule_mappings array that ties each change to the specific semver rule it triggers, and a justification for each mapping. This structure makes the output directly consumable by a CI gate that can block a release pipeline or flag it for human review.

Do not use this prompt for generating consumer-facing changelogs, drafting deprecation notices, or assessing the downstream impact on specific API consumers. Those are separate sibling workflows that require different context, tone, and output structures. This prompt also assumes the diff is accurate and complete; it does not detect missing changes or validate the diff itself. If your schema diff tool has known gaps—such as not detecting implicit type coercion risks or failing to flag field reordering in JSON—you must address those upstream before this prompt can produce a reliable verdict. For high-risk releases, always pair the automated verdict with a human review step, especially when the diff includes changes that are technically non-breaking but behaviorally significant, such as bugfixes that alter response values without changing the schema.

This prompt template is designed to be pasted directly into your AI system, forming the core instruction set for a semantic versioning compliance check. It instructs the model to act as a release engineer, comparing a set of schema changes against a declared version bump. The goal is not just a pass/fail verdict, but a detailed, rule-by-rule justification that maps each change to major, minor, or patch criteria, making the reasoning auditable for your release pipeline.

textCopy
You are a release engineer validating a version bump against a set of API schema changes. Your task is to produce a structured semver compliance report.

# INPUTS
- [CURRENT_SCHEMA]: The existing API schema before changes.
- [PROPOSED_SCHEMA]: The new API schema after changes.
- [DECLARED_VERSION_BUMP]: The version change the team intends to release (e.g., "1.2.0 to 1.3.0").
- [CHANGE_LOG]: A human-readable list of intended changes.

# CONSTRAINTS
- Apply strict Semantic Versioning 2.0.0 rules.
- A MAJOR bump is required for any incompatible API change (e.g., removing a field, changing a field type, making an optional field required).
- A MINOR bump is required for new, backward-compatible functionality (e.g., adding a new optional field or endpoint).
- A PATCH bump is required for backward-compatible bug fixes that do not change the public API contract.
- If a bug fix changes the API's observable behavior for a consumer, it is a BREAKING CHANGE and requires a MAJOR bump.
- Justify every finding with a specific reference to the schema diff.

# OUTPUT_SCHEMA
{
  "compliance_verdict": "COMPLIANT" | "NON_COMPLIANT",
  "declared_bump": "[DECLARED_VERSION_BUMP]",
  "required_bump": "MAJOR" | "MINOR" | "PATCH",
  "findings": [
    {
      "change_description": "String describing the schema change.",
      "change_type": "ADDITION" | "REMOVAL" | "MODIFICATION",
      "location": "Path to the changed element in the schema (e.g., 'paths./users.get.parameters[0].name').",
      "semver_impact": "MAJOR" | "MINOR" | "PATCH",
      "justification": "Explanation of why this change maps to the stated semver impact, referencing specific rules."
    }
  ],
  "summary": "A concise explanation of the verdict, highlighting the most impactful finding."
}

# RISK_LEVEL
- HIGH. An incorrect verdict can lead to broken consumer integrations. If the schemas are complex or the diffs are ambiguous, flag the finding for human review by setting a `requires_human_review` boolean to true in the finding object.

To adapt this template, replace the square-bracket placeholders with real data before execution. The [CURRENT_SCHEMA] and [PROPOSED_SCHEMA] should be the full OpenAPI or GraphQL schema strings. The [DECLARED_VERSION_BUMP] is a simple string, and [CHANGE_LOG] provides crucial human intent that the model can cross-reference against the raw diff. For high-stakes releases, ensure the OUTPUT_SCHEMA is enforced with your model's JSON mode or a downstream validator to prevent malformed reports from blocking your CI/CD pipeline.

This prompt is designed to act as a pre-release gate in a CI/CD pipeline. It should be invoked after a schema diff is generated (for example, from an OpenAPI, GraphQL, or gRPC specification comparison) but before the release tag is created. The harness is responsible for preparing the diff input, calling the model, validating the structured output, and deciding whether to block the release, flag it for human review, or allow it to proceed. The primary integration point is a shell script or CI job step that runs git diff or a dedicated schema-diff tool, pipes the result into the prompt, and captures the JSON verdict.

The implementation should follow a validate-retry-escalate pattern. First, parse the model's JSON output and validate it against a strict schema that requires fields like recommended_bump (one of major, minor, patch), breaking_changes (array of objects with location and justification), and confidence_score (0.0-1.0). If validation fails or the output is malformed, retry the prompt once with an explicit error message appended to the input. If the retry also fails, the pipeline should escalate to a human reviewer via a PR comment or ticketing system rather than silently passing or failing. For model choice, use a model with strong structured output capabilities (such as gpt-4o or claude-3.5-sonnet) and set temperature=0 to maximize determinism.

Logging and traceability are critical for audit and debugging. The harness should log the full prompt input (the schema diff), the raw model response, the parsed JSON output, and the final gate decision (pass/fail/escalate) as artifacts attached to the CI run. This creates an audit trail for release managers and allows post-mortem analysis of false positives or missed breaking changes. Additionally, implement a manual override mechanism—a file in the repository (e.g., .semver-overrides.json) that allows teams to document intentional breaking changes that should not block the release, along with a justification. The harness should check this file before failing the build.

To prevent prompt drift and ensure reliability, treat the prompt template as a versioned artifact stored alongside the application code. Use a dedicated test suite with golden diffs that have known, expected semver outcomes (e.g., adding an optional field should yield minor, removing a required field should yield major). Run these tests in CI whenever the prompt template changes. For high-risk repositories, consider running the check in advisory mode initially—posting the report as a PR comment without blocking merges—until the team has calibrated the prompt's accuracy and tuned the override list. Avoid wiring the prompt directly to an automated git tag command without human review for the first several release cycles.