Migration Guide Generation from Deprecation Notices Prompt

This prompt is designed for teams that need to produce accurate, actionable migration guides when features, APIs, or SDK methods are deprecated. It takes a deprecation notice and supporting repository context as input and produces a structured migration guide with step-by-step instructions, before/after code examples, a deprecation timeline, and rollback guidance. Use this prompt when you have a formal deprecation notice and need to generate developer-facing documentation that reduces support burden and accelerates adoption of replacement APIs. This prompt belongs in a workflow where a human reviews the output before publication, because incorrect migration instructions can break consumer builds.

The ideal user is a developer relations engineer, platform team member, or technical writer who already has a source deprecation notice and access to the relevant codebase. The prompt requires a concrete [DEPRECATION_NOTICE] input, such as a changelog entry, an RFC, or an API specification diff, along with [REPOSITORY_CONTEXT] that includes the deprecated surface and its replacement. Do not use this prompt when the replacement API is still under active design, when the deprecation timeline is not yet committed, or when you lack access to the source code of both the deprecated and replacement surfaces. In those cases, the model will produce plausible but incorrect guidance that can mislead consumers.

Before running this prompt, assemble the deprecation notice, the relevant source files, and any existing migration notes. The prompt works best when you also provide an [OUTPUT_SCHEMA] that defines the expected structure—typically including sections for a summary, a timeline, step-by-step instructions, before/after code examples, and rollback procedures. After generation, validate the output against the source code with automated checks: confirm that every deprecated method, class, or endpoint mentioned in the notice appears in the guide, that code examples compile against the current replacement API, and that the timeline matches the official deprecation policy. A human reviewer must then verify the instructions end-to-end before publication.

The following prompt template is designed to be copied directly into your AI harness or development environment. It accepts a deprecation notice, relevant API documentation, and optional constraints as inputs, then produces a structured migration guide with before/after code examples, a timeline, and rollback guidance. Every square-bracket placeholder must be replaced with actual data before sending the prompt to the model. Do not leave any placeholder unresolved in production requests—missing context produces unreliable output.

codeCopy
You are a technical documentation engineer specializing in API migration guides.

Your task is to generate a step-by-step migration guide from the deprecation notice and supporting documentation provided below.

## INPUTS

[DEPRECATION_NOTICE]

[API_DOCUMENTATION]

[CODEBASE_EXAMPLES]

## CONSTRAINTS

[CONSTRAINTS]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "migration_guide": {
    "title": "string",
    "deprecated_surface": "string",
    "effective_date": "string (ISO 8601)",
    "removal_date": "string (ISO 8601 or 'TBD')",
    "urgency": "string (low | medium | high | critical)",
    "summary": "string (2-4 sentence plain-English summary of what is changing and why)",
    "affected_endpoints_or_interfaces": ["string"],
    "steps": [
      {
        "step_number": "integer",
        "action": "string (clear imperative instruction)",
        "before_code": "string (code block showing deprecated usage)",
        "after_code": "string (code block showing new usage)",
        "notes": "string (caveats, edge cases, or alternative approaches)"
      }
    ],
    "rollback_steps": ["string"],
    "verification_checks": ["string (how to confirm migration succeeded)"],
    "breaking_changes": ["string (list of behaviors that will break if not migrated)"],
    "references": ["string (links to relevant docs, issues, or announcements)"]
  },
  "completeness_report": {
    "deprecated_surfaces_covered": ["string"],
    "deprecated_surfaces_missed": ["string"],
    "confidence": "string (high | medium | low)",
    "gaps_notes": "string (explain any missing coverage or assumptions made)"
  }
}

## INSTRUCTIONS

1. Parse the [DEPRECATION_NOTICE] to identify every deprecated endpoint, method, parameter, or behavior.
2. Cross-reference with [API_DOCUMENTATION] to find the replacement surface for each deprecated item.
3. Use [CODEBASE_EXAMPLES] to produce realistic before/after code snippets. If no examples are provided, generate representative examples based on the API documentation.
4. Order migration steps by dependency: foundational changes first, dependent changes later.
5. Include explicit rollback steps for each migration action where rollback is possible.
6. Flag any deprecated surface mentioned in the notice that lacks a documented replacement in the completeness report.
7. If [CONSTRAINTS] specifies a target audience, adjust code examples and language complexity accordingly.
8. Do not invent deprecation dates, version numbers, or API surfaces not present in the input materials.

Adapting the template: Replace [DEPRECATION_NOTICE] with the full text of the deprecation announcement, including any version timelines and affected surface lists. Replace [API_DOCUMENTATION] with the relevant reference docs for both the deprecated and replacement surfaces—include endpoint signatures, parameter tables, and authentication changes. Replace [CODEBASE_EXAMPLES] with real usage snippets from your codebase, or omit this section if you want the model to generate representative examples from the API docs alone. Replace [CONSTRAINTS] with audience-specific instructions such as "Target audience: frontend developers using the React SDK" or "Include only breaking changes; omit cosmetic deprecations."

Before shipping: Run this prompt against a known deprecation notice where you already have a manually written migration guide. Compare the model output to your reference guide across three dimensions: completeness (are all deprecated surfaces covered?), code correctness (do the before/after examples compile or run?), and step ordering (are dependencies respected?). If the model misses deprecated surfaces or invents replacement APIs not present in the documentation, add explicit negative constraints to the [CONSTRAINTS] block. For high-risk migrations affecting production systems, always route the generated guide through human review before publication.

The Migration Guide Generation from Deprecation Notices prompt is designed to be integrated into a release automation pipeline, not used as a one-off chat interaction. The core workflow involves fetching a structured deprecation notice (or a set of notices), assembling the prompt with the required context, calling a capable model, and then running a series of validation and verification steps before the output is ever shown to a developer. The primary integration points are your CI/CD system (e.g., GitHub Actions), your internal API gateway, and your documentation platform. The prompt's value is realized only when its output is trustworthy, which requires a harness that enforces structure, factuality, and completeness.

To wire this into an application, start by defining the input contract. The [DEPRECATION_NOTICES] placeholder should be a structured JSON array, not raw text. Each object must include api_surface, deprecation_date, removal_date, reason, and replacement_guidance. This structured input allows the harness to programmatically verify that the generated guide covers every deprecated surface listed in the input. The model call itself should be wrapped in a function that enforces a strict JSON output schema using the model's native structured output capabilities (e.g., OpenAI's response_format with a JSON Schema or a tool definition). The expected output schema should include a migration_steps array, each with step_number, action, code_before, code_after, and rollback_instructions. If the model's response fails to parse against this schema, the harness must trigger a retry with a repair prompt, not silently fall back to a raw text response.

The most critical part of the harness is the post-generation verification layer. After a valid JSON output is received, a separate evaluation step must run. This step uses a factuality-checking prompt (see the 'Release Note Hallucination and Factuality Check Prompt' playbook) to verify that every code_before example in the migration guide can be traced back to a real, deprecated API surface in the input notices. Any invented or hallucinated code example is a critical failure. Additionally, a completeness check must iterate through the input [DEPRECATION_NOTICES] array and confirm that each notice has a corresponding entry in the generated guide's migration_steps. A missing step for a known deprecation is a blocking error. These checks should be implemented as automated gates in your CI pipeline, producing a pass/fail report.

For high-risk or widely-used APIs, insert a human-in-the-loop approval step after automated verification passes. The harness should publish the generated guide as a draft pull request in your documentation repository, tagging the responsible API team for review. The PR description should include the automated verification report, highlighting any low-confidence steps or warnings. Do not automatically merge and publish the guide. The final step is to log the entire interaction: the input notices, the raw prompt, the model's raw response, the parsed output, and the verification results. This audit trail is essential for debugging failures, improving the prompt over time, and demonstrating governance to compliance teams. Avoid using this prompt for security-sensitive deprecations where a migration guide could inadvertently reveal attack surfaces before a patch is widely deployed.