API Contract Migration Guide Generation Prompt

This prompt is designed for developer relations engineers and API platform teams who need to convert a structured list of breaking API changes into a comprehensive, human-readable migration guide. The ideal input is a validated breaking change diff from a tool like an OpenAPI comparator or a manual contract review. The prompt assumes the breaking changes are already identified, categorized, and accurate—it does not perform the diff itself. The primary job-to-be-done is turning technical change data into a document that API consumers can follow step-by-step, complete with before/after code examples, a prioritized upgrade order for affected endpoints, and clear client-side action items.

Do not use this prompt when the breaking change list is unverified, incomplete, or speculative. If you haven't confirmed that a change is truly breaking—for example, distinguishing between a field addition (safe) and a type narrowing (breaking)—the guide will propagate errors that cause integration failures downstream. Similarly, this prompt is not a substitute for a breaking change detection tool; pair it with the Breaking Change Detection Prompt for OpenAPI Specs or a manual contract review before feeding changes into this guide generation workflow. For GraphQL, gRPC, or AsyncAPI contracts, use the schema-specific review prompts first to produce the structured change list, then feed that list into this prompt.

Before running this prompt, ensure you have: (1) a validated list of breaking changes with affected endpoints, (2) the previous and current API contract versions for code example generation, (3) client usage data if you need to prioritize endpoints by impact, and (4) your organization's deprecation policy and migration timeline requirements. The output should be reviewed by an engineer familiar with the API surface before publication, especially for changes that affect authentication, pagination, or error handling contracts. After generating the guide, validate completeness by checking that every breaking change in the input list appears in the output, and test the code examples against the current API version to catch syntax or behavioral drift.

This prompt template is designed for developer relations engineers who need to convert a structured list of breaking API changes into a comprehensive, step-by-step migration guide. The template accepts a breaking change diff, target audience context, and output formatting constraints. It instructs the model to produce a document with before/after code examples, affected endpoints, and a recommended client upgrade order. The placeholders allow you to inject the specific change data, your API's terminology, and any required output schema without modifying the core instruction logic.

textCopy
You are a senior developer relations engineer writing a migration guide for an API upgrade.

Your task is to convert the provided breaking change list into a clear, actionable migration document for our API consumers.

## INPUT
[BREAKING_CHANGE_DIFF]

## TARGET AUDIENCE
[AUDIENCE_CONTEXT]

## OUTPUT STRUCTURE
Generate a migration guide with the following sections:
1. **Overview**: A 2-3 sentence summary of the release, the primary breaking changes, and the urgency of the upgrade.
2. **Breaking Changes**: For each breaking change in the input, provide:
   - **Change Description**: What changed and why.
   - **Affected Endpoints/Methods**: List specific API paths or SDK methods.
   - **Before**: A code snippet showing the old usage pattern.
   - **After**: A code snippet showing the new required usage pattern.
   - **Client Impact**: Explain what will break if the client does not update.
3. **Recommended Upgrade Order**: A numbered, ordered list of steps a client should follow to safely adopt the new version, starting with the most critical changes.
4. **Deprecation Timeline**: If applicable, map changes to the deprecation schedule provided in [DEPRECATION_SCHEDULE].

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

## OUTPUT FORMAT
[OUTPUT_SCHEMA]

To adapt this template, replace each square-bracket placeholder with concrete data. [BREAKING_CHANGE_DIFF] should contain the structured list of changes, typically derived from an OpenAPI diff tool or a manual review. [AUDIENCE_CONTEXT] should describe the typical client, such as 'mobile SDK developers using our Kotlin library' or 'backend engineers integrating with our REST API in Python.' For [CONSTRAINTS], specify rules like 'use only GA features, not beta' or 'code examples must be in TypeScript.' [EXAMPLES] should include one or two high-quality before/after pairs to set the pattern. [OUTPUT_SCHEMA] can be a JSON schema, a Markdown template, or a simple format description. If the migration involves high-risk data changes, add a constraint requiring a warning callout for data-integrity-sensitive steps. Always validate the generated guide against the original breaking change list to ensure no change was omitted or misrepresented.

The API Contract Migration Guide Generation Prompt is designed to run as a step in a release pipeline, triggered when a breaking change diff is approved. The harness should receive a structured diff input—typically the output of a breaking change detection tool—along with the previous and current API spec versions. The prompt produces a draft migration guide, but the harness is responsible for validating that the output covers every breaking change in the input diff before the guide reaches a developer relations engineer for final polish.

Wire the prompt into an application by first constructing the [BREAKING_CHANGE_DIFF] input from your spec comparison tool. This should be a JSON array of change objects, each containing the endpoint path, the changed element (field, enum value, type, parameter), the before/after values, and a severity classification. Pass this alongside [API_NAME], [FROM_VERSION], and [TO_VERSION] into the prompt template. After the model responds, run a completeness validator that extracts all referenced breaking changes from the generated guide and compares them against the input diff. Flag any missing changes for a retry or manual insertion. For high-risk migrations, add a human review gate that requires a DevRel engineer to confirm the before/after code examples are correct and the upgrade order recommendations match known client dependencies. Log every generation with the input diff hash, output guide, completeness score, and reviewer identity for audit trails.

Choose a model with strong instruction-following and long-context handling—GPT-4o or Claude 3.5 Sonnet work well for structured document generation. Set temperature low (0.1–0.2) to reduce variation in code examples and endpoint lists. If the prompt fails completeness validation, implement a single retry with the validator's missing-change list appended as [MISSING_CHANGES] in the prompt context. Do not loop beyond one retry; instead, escalate to a human with the partial output and the gap report. Avoid wiring this prompt directly to a publishing step—always require human approval before the migration guide goes live in documentation.