Field Rename Migration Impact Prompt

Renaming a field in an API response is a breaking change that cascades through every consumer, cache layer, and serialization path. This prompt is designed for backend and platform teams who need a structured migration impact report before committing to the rename. It forces the model to reason about consumer dependencies, serialization formats, cache invalidation, and phased rollout sequencing. Use this prompt when you have a concrete field rename planned and need an impact analysis that goes beyond grep to identify hidden coupling points.

The ideal user is an engineering lead or senior backend engineer who already knows which field they intend to rename and has access to the API specification, client registry, and deployment topology. The prompt requires several concrete inputs: the current field name, the proposed new name, the affected endpoint or schema definition, a list of known consumers (internal services, SDKs, webhooks, external integrations), and the serialization format in use. Without these inputs, the model will produce a generic risk summary rather than an actionable migration plan. Do not use this prompt for simple additive field additions or type changes where a rename is not involved—those scenarios require different analysis patterns focused on backward compatibility rather than coordinated migration sequencing.

Before running this prompt, gather your consumer inventory and serialization details. The output should be treated as a starting point for migration planning, not a final execution plan. Always validate the identified coupling points against your actual codebase and monitoring data. For high-traffic production APIs, pair this analysis with a human review of the phased rollout recommendations and ensure your observability stack can track dual-write and deprecation window metrics before executing any rename.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a backend migration analyst, consuming a description of the proposed field rename, the API specification, and a client inventory. The model will produce a structured impact report that identifies every affected consumer, serialization path, and cache invalidation point, culminating in a phased migration plan with dual-write and deprecation window recommendations.

markdownCopy
You are a backend migration analyst. Your task is to produce a comprehensive migration impact report for renaming a field in an API response.

## Inputs
- [API_SPECIFICATION]: The current OpenAPI or GraphQL schema.
- [FIELD_RENAME_PLAN]: A description of the field to be renamed, including its current name, proposed new name, and the rationale.
- [CLIENT_INVENTORY]: A list of known API consumers, including SDKs, internal services, and external integrations, with their contact points.
- [CACHE_CONFIGURATION]: Details on CDN, reverse proxy, and application-level caching strategies in use.

## Task
1.  **Impact Analysis:** Identify every location in the [API_SPECIFICATION] where the field appears (paths, responses, models).
2.  **Consumer Mapping:** For each affected location, map it to specific consumers from the [CLIENT_INVENTORY] that are known to use those endpoints.
3.  **Serialization Path Audit:** Trace the field through any server-side serialization, transformation, or data mapping layers described in the provided context.
4.  **Cache Invalidation Assessment:** Based on the [CACHE_CONFIGURATION], identify all cache keys and invalidation strategies that will be impacted by the rename.
5.  **Migration Plan:** Generate a phased migration plan with the following stages:
    - **Phase 1: Dual-Write:** Add the new field name alongside the old one in all responses.
    - **Phase 2: Client Migration:** A deprecation window strategy, including notification templates and deadlines for each consumer to migrate to the new field.
    - **Phase 3: Deprecation:** Mark the old field as deprecated in the API specification.
    - **Phase 4: Removal:** A plan for the final removal of the old field after all consumers have migrated.

## Output Schema
Return your analysis as a single JSON object with the following structure:
{
  "field_rename_summary": {
    "current_name": "string",
    "proposed_name": "string",
    "rationale": "string"
  },
  "impact_assessment": {
    "affected_endpoints": [
      {
        "path": "string",
        "method": "string",
        "response_model": "string",
        "serialization_impact": "string"
      }
    ],
    "affected_consumers": [
      {
        "consumer_name": "string",
        "contact": "string",
        "impacted_endpoints": ["string"],
        "estimated_migration_effort": "low|medium|high|critical"
      }
    ],
    "cache_invalidation_points": [
      {
        "cache_layer": "string",
        "affected_keys": ["string"],
        "invalidation_strategy": "string"
      }
    ]
  },
  "migration_plan": {
    "phase_1_dual_write": {
      "implementation_steps": ["string"],
      "rollback_plan": "string"
    },
    "phase_2_client_migration": {
      "deprecation_window_days": "number",
      "consumer_notifications": [
        {
          "consumer_name": "string",
          "notification_template": "string",
          "migration_deadline": "string"
        }
      ]
    },
    "phase_3_deprecation": {
      "spec_update_steps": ["string"]
    },
    "phase_4_removal": {
      "pre_removal_checklist": ["string"],
      "removal_steps": ["string"]
    }
  },
  "risk_register": [
    {
      "risk_description": "string",
      "severity": "low|medium|high|critical",
      "mitigation": "string"
    }
  ]
}

## Constraints
- Do not propose a rename if the field is part of a public, unversioned API without a clear deprecation policy.
- Flag any consumer in the [CLIENT_INVENTORY] that lacks a clear owner or contact as a critical risk.
- The dual-write phase must be strictly additive and not change the behavior of the old field.
- All cache invalidation steps must be verified to prevent serving stale data during the migration.

To adapt this template, replace each square-bracket placeholder with concrete data from your environment. For the [API_SPECIFICATION], paste the relevant subset of your OpenAPI or GraphQL schema. The [CLIENT_INVENTORY] should be a structured list, even if it's just a markdown table of known consumers. If a section like [CACHE_CONFIGURATION] is unknown, replace it with a statement like 'No formal cache configuration is documented; assume standard CDN and application-level response caching.' The output schema is strict JSON; ensure your AI harness's response format is set to JSON mode or that you have a robust JSON repair step in your pipeline to handle any deviations.

This prompt is designed to run as a pre-merge review gate in CI, triggered by pull requests that modify API schema files (OpenAPI, GraphQL, Proto, or JSON Schema). The harness should extract the old and new schema versions from the PR diff, populate the [CURRENT_SCHEMA] and [PROPOSED_SCHEMA] placeholders, and inject the [CONSUMER_REGISTRY]—a structured list of known clients, their SDK versions, and their observed field usage from production telemetry. Without the consumer registry, the prompt cannot produce per-client impact estimates, only a generic breaking change classification. The harness should also supply [CACHE_CONFIG] describing CDN, Redis, and client-side cache TTLs so the prompt can flag cache invalidation timing risks.

Validation and output contract. The prompt must return a JSON object matching a strict schema: a field_rename object with old_name, new_name, and location; a breaking boolean; a consumers_affected array with name, usage_observed, and breakage_description per consumer; a serialization_paths array of code paths that serialize the field; a cache_invalidation_points array; and a migration_plan object with dual_write_period_days, deprecation_window_days, and phases. The harness must validate this schema immediately after the model response. If validation fails, retry once with the validation error appended to [CONSTRAINTS]. If the second attempt also fails, fail the CI check and surface the raw output for manual review. Do not silently accept malformed output.

Model choice and grounding. Use a model with strong structured output support (GPT-4o with response_format, Claude 3.5 Sonnet with tool use, or equivalent). The prompt relies on the model reasoning over schema diffs and consumer telemetry, not on external retrieval. However, the harness should ground the consumer registry by pulling it from a live service catalog or API gateway metrics system at runtime—never hardcode it in the prompt template. For high-risk renames (fields present in >10 consumer paths or fields marked required in any published spec), the harness must add [RISK_LEVEL]: high and require a human approval step before the CI check passes. The approval gate should display the full migration impact report and require sign-off from an API platform team member.

Logging and observability. Log every prompt invocation with a trace ID, the schema diff hash, the consumer registry version, the model response, the validation result, and the final CI verdict. Store these in a queryable format (structured logs or an eval database) so the team can audit past migration decisions, debug false positives, and track prompt drift over time. If the prompt flags a field rename as non-breaking but a production incident later proves otherwise, the trace log becomes the starting point for root cause analysis and prompt improvement. Wire the harness to emit a prompt_eval metric (pass/fail/retry/human_approval) to your observability stack.

What to avoid. Do not run this prompt on every commit—only on PRs that touch schema files with detected field renames. Do not use the prompt to automatically approve or merge changes; it is an advisory review tool, not an authorization system. Do not skip the consumer registry step and rely on the model to guess which clients are affected—the model has no access to your production traffic patterns. Finally, do not treat the migration plan as executable; the dual-write and deprecation windows are recommendations that require engineering review against your actual deployment pipeline and client upgrade cadence.