Migration Playbook Generation Prompt for Tool Consumers

Platform teams shipping breaking tool changes need a reliable way to generate step-by-step migration guides for downstream consumers. This prompt takes a structured breaking change list, old and new tool schemas, and produces a complete migration playbook with code snippets, config diffs, and verification steps. Use it when you have a defined set of breaking changes and need to produce consistent, actionable migration documentation at scale. The ideal user is a platform engineer or tool provider who already has a verified change list and needs to turn it into consumer-facing guidance without manually writing each guide.

Do not use this prompt when the change list is incomplete, unverified, or still under active development. If breaking changes haven't been finalized, the generated playbook will contain instructions that become incorrect after the next revision, creating downstream confusion and potential production incidents. Similarly, avoid this prompt when you need a general-purpose API reference or getting-started guide—this prompt is specifically tuned for migration documentation with before/after comparisons, not for introducing new concepts or explaining tool capabilities from scratch. The prompt assumes the consumer already understands the tool's purpose and only needs to adapt their integration.

Before running this prompt, validate that you have: (1) a complete, reviewed list of breaking changes with old and new behavior descriptions, (2) the old and new tool schemas in a structured format, (3) any migration deadlines or deprecation windows, and (4) known edge cases or common consumer patterns that need special attention. If any of these inputs are missing, the generated playbook will have gaps that require manual correction. For high-risk tool migrations where incorrect consumer adaptation could cause data loss, security issues, or service outages, always route the generated playbook through human review before publication. The prompt produces a draft that accelerates documentation, but it does not replace domain expertise or consumer impact analysis.

This prompt template is designed for platform teams that need to produce clear, actionable migration playbooks for consumers of their tools. It takes a structured list of breaking changes, the old and new tool specifications, and any relevant context, and outputs a complete migration guide. The prompt is engineered to not just list changes, but to generate the specific code modifications, configuration updates, and verification steps a developer needs to follow. It includes an explicit completeness check to ensure every breaking change in the input list is addressed in the output, preventing silent omissions.

markdownCopy
You are an expert migration engineer writing for developers who depend on our platform. Your task is to generate a complete, step-by-step migration playbook from an old tool version to a new one.

**Inputs:**
- Old Tool Specification: [OLD_TOOL_SPEC]
- New Tool Specification: [NEW_TOOL_SPEC]
- Breaking Change List: [BREAKING_CHANGE_LIST]
- Consumer Context (optional): [CONSUMER_CONTEXT]
- Output Schema: [OUTPUT_SCHEMA]

**Instructions:**
1.  Analyze the [BREAKING_CHANGE_LIST] and the differences between [OLD_TOOL_SPEC] and [NEW_TOOL_SPEC].
2.  For each breaking change, generate a dedicated migration step that includes:
    - **Change Description:** A clear, one-sentence summary of what broke.
    - **Before Code:** A code snippet showing the old, now-invalid usage pattern.
    - **After Code:** A code snippet showing the new, correct usage pattern.
    - **Configuration Update:** Any required changes to configuration files, environment variables, or initialization code.
    - **Verification Step:** A specific command, script, or check a developer can run to confirm the migration was successful for this step.
3.  After generating all steps, perform a **Completeness Check**:
    - Iterate through every item in the original [BREAKING_CHANGE_LIST].
    - Verify that a corresponding migration step exists in your output.
    - If any item is missing, generate the missing step(s) now.
    - Append a final "Migration Completeness Confirmation" section that lists each breaking change from the input and confirms it was addressed.
4.  Format the entire output according to the [OUTPUT_SCHEMA] provided. If the schema requires a structured JSON object, ensure strict compliance.
5.  If [CONSUMER_CONTEXT] is provided, tailor code examples and configuration paths to that specific environment. Otherwise, use generic but realistic examples.

**Constraints:**
- Do not omit any item from the [BREAKING_CHANGE_LIST].
- Code examples must be syntactically correct for the target language implied by the context or schemas.
- If a breaking change cannot be fully automated, clearly state the required manual intervention and its risk.

To adapt this template, start by populating the [OLD_TOOL_SPEC] and [NEW_TOOL_SPEC] placeholders with the full JSON Schema, OpenAPI specs, or structured documentation for your tool versions. The [BREAKING_CHANGE_LIST] should be a structured list, ideally as a JSON array of objects with id and description fields, to enable the model's completeness check. For high-risk production migrations, always route the generated playbook through a human review stage before publishing it to consumers. You can validate the output's completeness by running a separate evaluation prompt that compares the generated steps against the original breaking change list, flagging any missing IDs for manual correction.

This prompt is designed to be called programmatically, not pasted into a chat UI. It expects structured inputs—old and new tool schemas, a breaking change list, and optional code samples—and produces a structured migration guide. The harness should treat this as a generation step in a larger pipeline: validate inputs, call the model, validate the output, and then route the result to documentation systems or consumer-facing portals. Do not expose the raw prompt to end users; it is a platform-internal tool for engineering teams publishing migration guidance.

Input assembly is the first harness responsibility. Collect the old schema, new schema, and breaking change list from your API registry or schema repository. If code samples are available, attach them as [EXAMPLES]. Map these into the prompt's placeholders before invocation. Model choice matters: use a model with strong instruction-following and long-context handling (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set temperature low (0.0–0.2) to maximize consistency across regenerations. Output validation must check that every breaking change in the input list has a corresponding migration step in the output. Implement a completeness check: extract the list of addressed changes from the generated playbook and diff it against the input breaking change list. Flag any missing entries for human review. Also validate that code blocks in the output are syntactically valid for the target language if your pipeline can execute a linter.

Retry and repair logic should be built into the harness. If the completeness check fails, construct a repair prompt that includes the original output plus the list of uncovered breaking changes, and ask the model to generate only the missing sections. Merge the repair output into the original playbook. If the output fails schema validation (malformed JSON, missing required sections), retry with a stricter output format instruction appended to the prompt. Logging and audit are critical: record the prompt version, model version, input hashes, output completeness score, and any repair iterations. This traceability is essential when consumers question a migration step or when you need to regenerate playbooks after model upgrades. Human review should be the final gate before publication—especially for breaking changes that involve data loss, authentication shifts, or security boundary changes. The harness should route generated playbooks to a review queue with the completeness report attached.

Integration points depend on your tool ecosystem. For an internal developer portal, the harness can publish directly to a documentation API after review approval. For MCP server consumers, the generated playbook can be attached as a structured migration artifact alongside the new server version. For API changelog pipelines, wire this prompt downstream of your deprecation detection prompts so that detected breaking changes automatically trigger playbook generation. What to avoid: do not skip the completeness check—models will occasionally omit or merge breaking changes, especially when the change list is long. Do not treat the generated playbook as final without human review for high-severity changes. And do not call this prompt synchronously in a user-facing request path; the generation can take significant tokens and latency, so run it as an asynchronous job with results delivered to the appropriate publishing or review system.