Migration Guide Prerequisites Checklist Prompt

This prompt is for technical writers, release managers, and platform engineers who need to generate the 'Before You Begin' or 'Prerequisites' section of a version-to-version migration guide. Its job is to transform a structured inventory of breaking changes and target version metadata into a concrete, verifiable checklist of preconditions that consumers must satisfy before executing the first migration step. Use it when you have a finalized, reviewed list of breaking changes and need to ensure downstream consumers do not skip environment preparation, backup steps, or dependency upgrades that would cause a migration to fail silently or catastrophically.

The prompt requires two structured inputs to function reliably: a [BREAKING_CHANGE_INVENTORY] containing every documented breaking change with its affected surface, severity, and required consumer action, and a [TARGET_VERSION_INFO] block specifying the target version number, minimum required runtime or platform versions, and any new mandatory dependencies. Without these inputs, the prompt will hallucinate prerequisites or omit critical preconditions. The output is a markdown checklist where every item is actionable (the consumer can perform it and verify completion) and traceable to a specific breaking change or version requirement. For example, if a breaking change removes a deprecated authentication method, the checklist must include a step to verify that all clients use the replacement method before upgrading.

Do not use this prompt to discover breaking changes, write the step-by-step migration instructions, or draft the full migration guide. It is a focused tool for the prerequisites section only. If your breaking change inventory is incomplete or unverified, stop and complete that work first. In high-risk environments—such as database migrations, security-sensitive upgrades, or regulated infrastructure—pair this prompt's output with a human review gate and require evidence that each prerequisite has been satisfied before the migration proceeds. The next step after generating the checklist is to validate it against the full breaking change inventory using a completeness audit prompt, then wire it into your migration runbook or release automation.

This prompt template is designed to be wired into a documentation pipeline. It takes structured release artifacts—such as changelogs, dependency manifests, and configuration diffs—and produces a prerequisites section that is actionable and verifiable. The output is not a narrative guide but a structured checklist where every item can be confirmed or rejected by a downstream consumer.

textCopy
You are a technical documentation engineer preparing a migration guide.

Your task is to produce a prerequisites checklist for upgrading from [SOURCE_VERSION] to [TARGET_VERSION] of [PRODUCT_NAME].

Use the following inputs:
- Release changelog: [CHANGELOG]
- Dependency manifest diff: [DEPENDENCY_DIFF]
- Configuration schema changes: [CONFIG_DIFF]
- Deprecated surface inventory: [DEPRECATED_SURFACES]
- Known issues list: [KNOWN_ISSUES]

For each prerequisite, include:
1. A clear, imperative action (e.g., "Upgrade the database client library to v3.2 or later").
2. The reason this action is required (e.g., "The v2.x client cannot parse the new wire protocol introduced in [TARGET_VERSION]").
3. A verifiable check (e.g., "Run `npm list db-client` and confirm the version is >= 3.2.0").
4. A category: [ENVIRONMENT_PREP | PERMISSIONS | DEPENDENCY_UPGRADE | CONFIG_CHANGE | DATA_BACKUP | DEPRECATION_CHECK | OTHER].

Constraints:
- Every prerequisite must be traceable to a specific entry in the provided artifacts.
- Do not invent prerequisites that are not supported by the inputs.
- If a prerequisite cannot be verified by the consumer, flag it with [VERIFICATION_GAP].
- Group prerequisites by category and order them by dependency (e.g., environment prep before dependency upgrades).
- If a prerequisite has a known workaround or is optional, mark it clearly.

Output format:
```json
{
  "source_version": "[SOURCE_VERSION]",
  "target_version": "[TARGET_VERSION]",
  "prerequisites": [
    {
      "action": "string",
      "reason": "string",
      "verification": "string",
      "category": "string",
      "required": true,
      "workaround": "string or null",
      "source_artifact": "string"
    }
  ],
  "verification_gaps": ["string"]
}

To adapt this template, replace each square-bracket placeholder with data extracted from your release pipeline. The [CHANGELOG] should be the structured diff between the two versions, not a marketing summary. The [DEPRECATED_SURFACES] input should come from a prior deprecation flagging step. Before shipping, run the output through a validation harness that cross-references every prerequisite against the source artifacts and flags any item that cannot be traced back to a specific change. For high-risk migrations, route the generated checklist through a human reviewer who can confirm that no critical prerequisite was omitted.

The prerequisites checklist prompt is designed to sit inside a documentation generation or review pipeline, not as a standalone chat interaction. The typical integration point is after a breaking change enumeration has been produced and before the full migration guide is drafted. The prompt receives structured inputs—version numbers, dependency manifests, configuration schemas, and the breaking change inventory—and outputs a structured prerequisites section that downstream guide assembly prompts can consume. Because missing or incorrect prerequisites cause real consumer breakage, the harness must enforce validation, completeness checks, and human review before the output reaches a published guide.

Wire the prompt into your pipeline as a discrete step with a defined input contract and output schema. Inputs should include: [CURRENT_VERSION] and [TARGET_VERSION] as semver strings; [BREAKING_CHANGE_INVENTORY] as a structured list of changes with affected surfaces; [DEPENDENCY_MANIFEST] as parsed package.json, requirements.txt, or equivalent; [CONFIG_SCHEMA] as the full configuration reference for both versions; [AUTH_SCOPE_DIFF] if permissions or scopes changed; and [ENVIRONMENT_REQUIREMENTS] such as runtime versions, OS constraints, or infrastructure prerequisites. Output schema should enforce a JSON structure with fields: minimum_version_requirements, required_permissions, dependency_upgrades, configuration_backups, environment_preparation, and pre_flight_checks. Each field must contain an array of actionable items with description, verification_command (a runnable check), and blocking (boolean indicating whether failure prevents migration). Validate the output programmatically: every verification_command must be non-empty and syntactically plausible for the target environment; every prerequisite must reference at least one breaking change from the input inventory or a version-specific requirement from the dependency manifest; and no prerequisite should be purely advisory without a verifiable check.

Model choice and retry strategy matter here. Use a model with strong instruction-following and structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set response_format to JSON schema mode if the provider supports it, or use a strict parser with a retry loop. On validation failure, feed the validation errors back into a retry prompt that includes the original inputs, the failed output, and the specific validation failures. Limit retries to 3 attempts, then escalate to a human reviewer queue with the partial output and error log. Logging and observability should capture: the prompt version hash, input hashes, output schema compliance status, validation pass/fail per field, retry count, and final reviewer decision. This audit trail is essential when a consumer reports a missing prerequisite—you can trace whether the prompt omitted it, validation missed it, or a human reviewer overrode it. Human review is mandatory before publication. Present the reviewer with the structured checklist, the source breaking change inventory, and a diff of any items that failed validation or were added during retry. The reviewer should confirm that every breaking change with a prerequisite has a corresponding checklist item and that no verification command would cause harm if executed. For high-risk migrations involving data loss potential or auth scope changes, add a second reviewer or a required sign-off gate in your documentation CMS.

When this prompt is not enough, you need product code or additional tooling. If your migration involves database schema changes, the verification commands should invoke actual schema comparison tools, not just echo commands. If your dependency upgrades require resolving transitive conflicts, integrate a dependency resolver that runs before the prompt and feeds its output into [DEPENDENCY_MANIFEST]. If your configuration backups involve secrets, the prompt should reference your secrets management tooling by name but never handle secret values directly. The prompt produces a checklist for humans and automation to execute—it does not execute the checks itself. For fully automated migration pipelines, pair this prompt's output with a workflow engine that runs each verification_command, captures results, and blocks progression on blocking: true failures. The prompt's job is to ensure completeness and actionability; the harness's job is to enforce correctness and safety before any consumer sees the guide.