Enum Value Addition vs Removal Decision Prompt

API designers and platform engineers face a recurring decision when modifying enum types: is this change safe to ship, or will it break existing clients? Adding a value to an open enum is typically additive and safe. Removing a value, or adding a value to a closed enum that clients must handle, is breaking. This prompt classifies enum changes against your API's compatibility rules and outputs a structured decision guide with client upgrade path requirements. Use it during spec review, before merging OpenAPI or GraphQL schema changes, and in CI checks that gate breaking changes. The prompt assumes you can provide the enum definition before and after the change, plus your organization's enum extensibility policy.

This prompt is designed for teams that maintain public APIs, internal service contracts, or generated SDKs where enum evolution directly impacts serialization, deserialization, and client-side switch statements. It works best when you have a written enum extensibility policy—for example, 'all enums are open by default unless marked x-closed: true' or 'GraphQL enums are closed; REST enums are open.' Without a policy, the model will apply reasonable defaults, but the output should be treated as a recommendation rather than an authoritative ruling. The prompt expects two inputs: the enum definition before the change and the enum definition after the change. These can be provided as raw OpenAPI schema fragments, GraphQL enum definitions, or plain lists of values with a noted extensibility mode.

Do not use this prompt for changes that involve renaming enum values while preserving the underlying wire format—that is a separate compatibility question involving aliasing and deprecation. Do not use it when the enum is generated from a database lookup table or external configuration source where the source of truth lives outside the API spec. In those cases, the change classification must account for data migration and runtime behavior, not just contract compatibility. For high-risk APIs where an incorrect classification could cause revenue loss or data corruption, always route the prompt output through a human reviewer and pair it with contract testing in CI before allowing the spec change to merge.

The prompt below is designed to be dropped into an automated API review pipeline or a manual design review checklist. It forces the model to reason about enum semantics—specifically whether the enum is open or closed—before issuing a verdict. Replace every square-bracket placeholder with your actual enum definitions, API context, and policy rules before use. The prompt is self-contained: it includes the classification logic, output schema, and constraints so that the model does not need external retrieval to produce a useful decision guide.

textCopy
You are an API contract reviewer specializing in enum evolution safety. Your task is to classify a proposed enum change and produce a decision guide with client upgrade path requirements.

## INPUT
- Current enum definition: [CURRENT_ENUM_DEFINITION]
- Proposed enum definition: [PROPOSED_ENUM_DEFINITION]
- Enum name and location: [ENUM_NAME_AND_PATH]
- API context: [API_CONTEXT]
- Client inventory (if available): [CLIENT_INVENTORY]

## CLASSIFICATION RULES
1. Determine whether the enum is **open** (clients must handle unknown values gracefully) or **closed** (clients may fail on unknown values). State your determination and reasoning.
2. Classify the change as one of:
   - **SAFE_ADDITIVE**: Only new values added. No existing values removed or renumbered. Safe for all clients.
   - **BREAKING_REMOVAL**: One or more existing values removed. Breaking for clients that depend on removed values.
   - **BREAKING_RENUMBER**: Existing values renumbered or reordered in a way that changes wire format.
   - **REQUIRES_CLIENT_OPT_IN**: New required enum value added to a closed enum where clients cannot gracefully handle unknown values.
3. If the change is BREAKING_REMOVAL or BREAKING_RENUMBER, identify every removed or changed value and list the affected client paths.

## OUTPUT SCHEMA
Return a JSON object with exactly these fields:
{
  "enum_semantics": "open" | "closed",
  "semantics_rationale": "string explaining why the enum is open or closed",
  "change_classification": "SAFE_ADDITIVE" | "BREAKING_REMOVAL" | "BREAKING_RENUMBER" | "REQUIRES_CLIENT_OPT_IN",
  "affected_values": ["list of removed or changed enum values, empty if none"],
  "client_impact_summary": "string describing which clients are affected and how",
  "upgrade_path": "string with step-by-step migration guidance or 'No action required'",
  "rollback_risk": "low" | "medium" | "high",
  "recommendation": "proceed" | "block" | "require_client_migration" | "add_deprecation_window"
}

## CONSTRAINTS
- Do not assume enum semantics. Derive them from the API context, documentation patterns, or explicit client contracts provided.
- If the enum semantics cannot be determined, classify as closed (conservative default) and note the assumption.
- If client inventory is not provided, assume external clients exist and flag removal as high risk.
- Do not invent enum values or client paths not present in the input.
- If the change is SAFE_ADDITIVE for an open enum, upgrade_path must be 'No action required' and recommendation must be 'proceed'.

After pasting the template, adapt the [API_CONTEXT] placeholder with concrete details: Is this a public API with a published SDK? An internal service with known consumers? A database column with application-level enum validation? The more specific the context, the more reliable the open-vs-closed determination. For high-risk APIs (payments, auth, health data), always route the output through a human reviewer before merging the change. Wire the JSON output into a CI check that blocks PRs with a recommendation of block and flags require_client_migration for the release manager.

The Enum Value Addition vs Removal Decision Prompt is designed to sit inside a pre-merge API review gate, not as a standalone chatbot query. The typical integration point is a CI check that runs when an OpenAPI, GraphQL, or gRPC spec diff includes enum modifications. The harness extracts the enum change from the diff, constructs the prompt with the required context (enum name, old values, new values, spec type, and client inventory), and enforces a structured JSON output that downstream tooling can parse for automated decisions or review queue routing.

Validation is mandatory before trusting the output. The prompt returns a decision field (safe_additive, breaking_removal, requires_client_opt_in) and a client_upgrade_path. The harness must validate that the decision is one of the three expected values and that breaking_removal decisions always include a non-empty client_upgrade_path array. If the output fails schema validation, retry once with the validation error appended to the prompt as a correction hint. If the second attempt also fails, escalate to a human review queue with the raw diff and both failed outputs attached. Log every decision with the spec version, enum name, model used, and decision for auditability.

For closed enums (strict validation on the server), any value removal is breaking and the harness should auto-flag the change without calling the model—this is a deterministic rule, not a judgment call. For open enums (server tolerates unknown values), the model's classification is useful but the harness should still enforce a policy check: if the removal affects a value that appears in production client telemetry, escalate regardless of the model's safe_additive verdict. Wire the prompt into your existing API governance dashboard so that product managers can see enum change decisions alongside breaking change reports, not buried in a separate tool.