SDK Breaking Change Migration Guide Prompt

This prompt is designed for platform teams and SDK engineers who need to produce version-to-version migration documentation. It takes a structured changelog of breaking changes, deprecated surfaces, and new API mappings as input, and outputs a complete migration guide with before/after code comparisons, effort estimates, and a checklist verifying that every breaking change is addressed. Use this when you have a finalized list of breaking changes and need to generate the first draft of a migration guide that downstream developers can follow.

The ideal user is an SDK maintainer, release manager, or technical writer who has already completed the breaking change discovery and enumeration phase. The required input is a structured list where each entry includes the deprecated surface, the replacement API, the reason for the change, and the target version. Do not use this prompt to discover breaking changes from source code; it assumes the breaking change enumeration is already complete and accurate. For discovery, use a code analysis prompt or static analysis tooling before feeding the results into this migration guide generator.

Before running this prompt, ensure your input is a machine-readable changelog, not a free-form commit history. The prompt's value comes from its ability to enforce completeness: it will generate a checklist that maps every input breaking change to a migration path, flagging any gaps. After generation, you must validate the output against your actual API surface and run the provided code examples through a test harness to confirm they compile and execute correctly. This prompt is not a substitute for human review of migration guidance, especially for security-critical or revenue-impacting API surfaces.

This prompt template is designed to take a raw list of breaking changes—typically sourced from a changelog, commit history, or API diff—and produce a structured, developer-facing migration guide. It forces the model to address every listed change, map deprecated surfaces to their replacements, and provide before/after code comparisons. The output is intended to be a first draft that a platform engineer or technical writer can review, test, and publish. Do not use this prompt for additive features or non-breaking changes; it is specifically scoped to version-to-version breaking change communication.

textCopy
You are a technical documentation engineer for an SDK platform team. Your task is to produce a migration guide that helps developers upgrade from SDK version [OLD_VERSION] to [NEW_VERSION].

## INPUTS
- Breaking Change Changelog:
[BREAKING_CHANGES_LIST]

- Current API Surface Reference (optional, for replacement mapping):
[API_SURFACE_REFERENCE]

- Target Language and Framework:
[LANGUAGE_AND_FRAMEWORK]

- Migration Guide Style Guide or Template:
[STYLE_GUIDE]

## OUTPUT SCHEMA
Produce a JSON object with the following structure:
{
  "guide_title": "string",
  "version_from": "string",
  "version_to": "string",
  "summary": "string (2-3 sentence overview of impact and required action)",
  "breaking_changes": [
    {
      "change_id": "string",
      "category": "enum: method_removal | signature_change | behavior_change | config_change | dependency_change | auth_change",
      "severity": "enum: critical | high | medium | low",
      "deprecated_surface": "string (the old API, method, or behavior)",
      "replacement_surface": "string (the new API, method, or behavior, or null if no direct replacement)",
      "before_code": "string (code block showing old usage)",
      "after_code": "string (code block showing new usage)",
      "migration_steps": ["string (ordered step-by-step instructions)"],
      "effort_estimate": "enum: trivial | small | medium | large",
      "automatic_fix_available": "boolean (whether a codemod or automated migration tool exists)"
    }
  ],
  "deprecated_but_not_removed": [
    {
      "surface": "string",
      "scheduled_removal_version": "string",
      "replacement": "string"
    }
  ],
  "upgrade_checklist": ["string (ordered steps for the full upgrade process)"],
  "known_issues": ["string (any known problems or edge cases during migration)"]
}

## CONSTRAINTS
- Every entry in [BREAKING_CHANGES_LIST] must appear in the breaking_changes array. Do not skip or consolidate entries.
- Before and after code examples must be valid [LANGUAGE_AND_FRAMEWORK] syntax and compilable.
- If a deprecated surface has no direct replacement, set replacement_surface to null and explain the workaround in migration_steps.
- Categorize severity as critical if the change will cause a compilation error or runtime crash without code changes.
- If [API_SURFACE_REFERENCE] is provided, use it to verify replacement surface names and signatures. If not provided, infer replacements from the changelog descriptions.
- Follow [STYLE_GUIDE] for tone, formatting, and terminology if provided.
- Do not invent breaking changes not present in [BREAKING_CHANGES_LIST].

## EVALUATION CRITERIA
Before returning the output, verify:
1. The count of entries in breaking_changes matches the count of distinct breaking changes in [BREAKING_CHANGES_LIST].
2. Every critical or high severity change has a before/after code example.
3. No replacement_surface references an API that does not exist in [API_SURFACE_REFERENCE] (if provided).
4. The upgrade_checklist is ordered logically (e.g., auth changes first, then method migrations, then config updates).

To adapt this template, replace each square-bracket placeholder with your actual data. The [BREAKING_CHANGES_LIST] is the most critical input—it should be a structured list of every breaking change, ideally with the deprecated surface name, the reason for the change, and the intended replacement. If you are sourcing this from a git log or PR description, run a separate extraction prompt first to produce a clean list. The [API_SURFACE_REFERENCE] is optional but strongly recommended; providing the current public API surface (method signatures, type definitions, config options) significantly reduces hallucinated replacement names. After generating the guide, run the output through a validation step that checks code examples against the actual SDK to catch syntax errors or deprecated API usage before publication.

This prompt is designed to be called programmatically as part of a release workflow, not as a one-off chat interaction. The typical integration point is a CI/CD pipeline that triggers when a new SDK version is tagged. A script collects the changelog entries, deprecated surface list, and previous migration guide, then assembles the prompt with these inputs. The model call should be wrapped in a harness that validates the output structure before it ever reaches a documentation preview environment.

Start with input validation: confirm that the changelog contains at least one breaking change entry before invoking the model. If the changelog is empty or contains only additive changes, skip the prompt entirely and generate a simple 'no breaking changes' notice. For the model call itself, use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set temperature=0.1 to maximize consistency across regeneration. Request JSON output with a defined schema that includes breaking_changes (array of objects with title, before_code, after_code, replacement_api, effort_estimate), deprecated_surfaces (array of strings), and coverage_report (object with total_breaking_changes_in_changelog and addressed_count). If the model returns malformed JSON, retry once with the error message appended to the prompt as a correction hint. If the second attempt also fails, flag for human review rather than silently publishing broken output.

The coverage check is the most critical post-generation validation. Parse the output and compare addressed_count against total_breaking_changes_in_changelog. If they don't match, the prompt missed entries. In that case, extract the unaddressed changelog items and run a second pass with a targeted prompt that asks the model to generate migration entries only for those specific items, then merge the results. For code block validation, extract every before_code and after_code block and run them through a syntax checker for the target language. Flag any blocks that fail parsing. For effort estimate consistency, verify that estimates use a consistent scale (e.g., minutes, hours, days) and flag outliers for human review. Log every model call, the input changelog hash, the output JSON, validation results, and any retry attempts to an observability system for audit and debugging.

The final output should be rendered into a documentation page template, but do not publish automatically. Route the generated migration guide to a documentation preview environment and notify the SDK team through a pull request or Slack notification. Require at least one SDK engineer to verify that every breaking change is addressed with a correct migration path, that code examples compile against the new version, and that effort estimates are reasonable. Only after human approval should the guide be merged and published. For teams running this prompt on every release, maintain a regression test suite of known breaking change scenarios with expected migration entries, and run the prompt against these golden cases before processing real changelogs to catch prompt drift early.