Version-to-Version Migration Guide Drafting Prompt

Use this prompt when you are a technical writer, platform engineer, or release manager who has already completed the discovery phase of a version migration. You must have a finalized inventory of breaking changes, prepared before/after code comparisons, identified deprecated surfaces, and estimated the effort required for downstream consumers. The prompt assembles these structured inputs into a publication-ready migration guide that includes an overview, breaking change summary, prerequisites, step-by-step instructions, code comparisons, a troubleshooting section, and a rollback plan. It is designed to enforce internal consistency, such as ensuring every breaking change listed in the summary has a corresponding step in the instructions and a code example.

Do not use this prompt if you are still in the discovery phase of a migration. It will not analyze raw code diffs, changelogs, or OpenAPI specifications to identify breaking changes; that work should be done with a dedicated prompt like the 'Breaking Change Enumeration Prompt Template' or 'API Surface Diff Analysis Prompt.' Similarly, avoid this prompt for migrations that involve only additive, non-breaking changes, as its structure and validation logic assume the presence of breaking changes that require consumer action. Using it for a simple feature release will produce an overly complex document with empty or irrelevant sections. The prompt also assumes a single source of truth for your inputs; if your breaking change inventory is scattered across multiple tickets and documents, consolidate it first.

Before executing this prompt, validate that your inputs are complete and accurate. A missing code comparison or an unverified deprecation date will propagate errors into the final guide. After generation, you should run a 'Migration Guide Completeness Audit Prompt' to cross-reference the output against your source inventory and a 'Before/After Code Comparison Prompt' to verify that every code sample compiles against its target version. For high-risk migrations, always require a human review step to confirm that rollback instructions are safe and that troubleshooting guidance covers known edge cases from your test plan.

This prompt template is designed to produce a full migration guide document when provided with a structured inventory of breaking changes, version identifiers, code examples, and platform context. It is not a generic summarizer—it expects precise inputs and produces a document with an overview, breaking change summary, prerequisites, step-by-step instructions, code comparisons, troubleshooting, and a rollback plan. The template uses square-bracket placeholders so you can wire it directly into an automated documentation pipeline or a human-in-the-loop authoring tool.

textCopy
You are a technical writer producing a version-to-version migration guide for a software platform, API, or SDK. Your output must be accurate, internally consistent, and actionable for a developer audience. Do not invent changes, features, or timelines not present in the provided inputs.

## INPUTS

[BREAKING_CHANGE_INVENTORY]
(A structured list of every breaking change. Each entry must include: change ID, severity, affected surface, deprecated pattern, replacement pattern, and required consumer action.)

[BEFORE_AFTER_CODE_EXAMPLES]
(Side-by-side code blocks for each breaking change, annotated with behavioral differences, error handling changes, and import path updates. Each example must be tagged with the corresponding change ID.)

[VERSION_INFO]
(Source version, target version, release dates, deprecation timeline, and end-of-support dates.)

[PLATFORM_CONTEXT]
(Programming languages, frameworks, deployment environments, and any platform-specific constraints that affect migration steps.)

[KNOWN_ISSUES]
(Documented unresolved issues, edge cases, and planned fix timelines. Each issue must include a workaround if one exists.)

[ROLLBACK_TRIGGERS]
(Conditions that should cause a consumer to abort or reverse the migration, such as data consistency failures, performance regressions, or critical bug discoveries.)

## OUTPUT STRUCTURE

Produce a complete migration guide with the following sections in order:

1. **Overview**: One paragraph explaining what this migration covers, which versions are involved, and the primary motivation for upgrading. Include a severity summary (e.g., "This migration includes 3 critical breaking changes, 5 moderate changes, and 2 deprecation notices").

2. **Breaking Change Summary Table**: A table with columns: Change ID, Severity, Affected Surface, Required Action, and Link to Detailed Section. Every entry in [BREAKING_CHANGE_INVENTORY] must appear in this table.

3. **Prerequisites**: A numbered checklist of everything the consumer must do before starting migration. Derive these from [PLATFORM_CONTEXT] and [VERSION_INFO]. Include minimum version requirements, required permissions, dependency upgrades, configuration backups, and environment preparation. Every prerequisite must be verifiable.

4. **Step-by-Step Migration Instructions**: For each breaking change in [BREAKING_CHANGE_INVENTORY], produce a subsection with:
   - Change description and rationale
   - Before/after code comparison from [BEFORE_AFTER_CODE_EXAMPLES]
   - Step-by-step migration actions
   - Verification criteria (how to confirm the change was applied correctly)
   - Rollback step (how to reverse this specific change if it fails)
   Order changes by severity (critical first) and dependency (changes that must be done before others).

5. **Troubleshooting**: Common error scenarios derived from [KNOWN_ISSUES] and the error handling changes in [BEFORE_AFTER_CODE_EXAMPLES]. For each scenario, provide the symptom, probable cause, and resolution steps.

6. **Rollback Plan**: A complete rollback procedure triggered by [ROLLBACK_TRIGGERS]. Include pre-migration state capture instructions, step-by-step reversal, data consistency checks, and post-rollback verification.

7. **Known Issues**: A section listing each entry from [KNOWN_ISSUES] with description, affected scenarios, workaround, and planned fix timeline.

## CONSTRAINTS

- Every breaking change in [BREAKING_CHANGE_INVENTORY] must appear in the summary table and have a corresponding detailed section.
- Every code example in [BEFORE_AFTER_CODE_EXAMPLES] must be used exactly once and linked to the correct change ID.
- Do not fabricate error codes, timelines, or replacement APIs.
- If a breaking change has no direct replacement, state that explicitly and provide workaround guidance.
- If [KNOWN_ISSUES] is empty, state "No known issues at time of publication" rather than omitting the section.
- Use consistent terminology from [PLATFORM_CONTEXT] throughout.
- Cross-reference all sections so that a reader can navigate from summary table to detailed steps to rollback instructions without broken links.

## OUTPUT FORMAT

Output the complete migration guide as a single Markdown document. Use appropriate heading levels, code fences with language tags, and tables.

To adapt this template, replace each square-bracket placeholder with structured data from your release pipeline. The [BREAKING_CHANGE_INVENTORY] should be the output of a breaking change enumeration prompt or an API surface diff analysis. The [BEFORE_AFTER_CODE_EXAMPLES] should come from a dedicated code comparison prompt that validates both snippets compile against their respective versions. If you are wiring this into an automated pipeline, validate the output against a completeness audit prompt that cross-references the generated guide against the original breaking change inventory to catch omissions. For high-risk migrations where correctness is critical, always route the final guide through human review before publication.

This prompt is designed to be the final assembly step in a migration documentation pipeline, not a standalone tool. It expects structured inputs—a breaking change inventory, before/after code comparisons, a deprecation timeline, and replacement API mappings—that should be produced by upstream prompts or deterministic tooling. Wiring it directly to raw changelogs or commit diffs will produce an incomplete, hallucination-prone guide. The harness must validate that every required input section is populated before the prompt is invoked, and that the output guide references every breaking change enumerated in the source inventory.

The implementation harness should follow a validate → generate → audit → repair → review loop. First, validate that all input sections ([BREAKING_CHANGE_INVENTORY], [BEFORE_AFTER_EXAMPLES], [DEPRECATION_TIMELINE], [REPLACEMENT_MAPPINGS]) are non-empty and structurally complete. Second, invoke the model with the prompt template, capturing the raw output and the model version in logs. Third, run an automated audit using the Migration Guide Completeness Audit Prompt against the generated guide, cross-referencing it with the original breaking change inventory to detect omissions, broken cross-references, or hallucinated endpoints. Fourth, if the audit fails, feed the audit report back into a repair loop (using the Output Repair and Validation Prompts pillar patterns) with a maximum of two retries before escalating. Fifth, route any guide that passes automated audit to a human technical writer for final review, particularly for tone, troubleshooting accuracy, and rollback plan coherence.

For model choice, prefer a model with strong instruction-following and long-context handling, such as Claude 3.5 Sonnet or GPT-4o, given the volume of structured input this prompt consumes. Set temperature low (0.1–0.3) to reduce creative drift in technical instructions. Log every generation attempt, the audit report, the repair count, and the final human review outcome. Do not publish a migration guide that has not passed both the automated completeness audit and human review. The highest-risk failure mode is a guide that omits a breaking change—consumers following it will encounter undocumented failures. The second-highest is a guide that includes hallucinated endpoints or flags that do not exist in either version, which erodes trust in all future migration documentation.