Release Note Upgrade Instructions Generation Prompt

Use this prompt when you have completed a full breaking change analysis for a software release and need to produce an ordered, actionable upgrade guide for users or internal teams. The ideal user is a release manager, platform engineer, or technical writer who already possesses a validated breaking change manifest—a structured document listing every identified breaking change, its affected surface, severity, and required remediation category. The prompt transforms that manifest into a sequential procedure covering pre-flight checks, configuration updates, database migrations, code modifications, and rollback steps. This is a documentation-generation workflow, not a code-generation tool; the output is a human-readable guide that must be reviewed by an engineer familiar with the system before publication.

Do not use this prompt when breaking changes have not been fully identified, when the upgrade path is trivial (e.g., a single non-breaking dependency bump), or when you lack a complete manifest. The prompt assumes the input is exhaustive—if a breaking change is missing from the manifest, it will be absent from the generated instructions. Similarly, avoid this prompt for generating code patches, database migration scripts, or automated fix tools; it produces procedural documentation, not executable artifacts. For releases with zero breaking changes, a simpler changelog-generation prompt is more appropriate. The prompt also requires the manifest to include severity classifications and affected component tags; without these, the output ordering and prioritization will be unreliable.

Before using this prompt, validate your breaking change manifest for completeness: every entry should include the change description, affected API surface or component, severity level, required action type (e.g., config update, data migration, code change), and any version constraints. Run a completeness check against the full diff or changelog to confirm no breaking changes were missed. After generating the upgrade guide, an engineer must review the output for procedural correctness, ordering logic, and missing edge cases. Pair this prompt with the 'Release Note QA and Accuracy Verification Prompt' to audit the generated guide against source changes before publication. If the upgrade affects multiple services or repositories, consider using the 'Multi-Repo Aggregated Changelog Prompt' first to produce a unified manifest before generating instructions.

This template takes a structured breaking change manifest and produces a step-by-step upgrade guide. It is designed for teams that have already completed change analysis and need to convert raw impact data into clear, ordered procedures for downstream consumers. The prompt enforces a strict output schema so the generated instructions can be parsed, validated, and embedded directly into release notes or migration documentation.

textCopy
You are a technical release engineer writing upgrade instructions for a software release.

Your task is to convert the provided breaking change manifest into an ordered, step-by-step upgrade guide. The guide must be complete, actionable, and safe for operators to follow.

## INPUT

[BREAKING_CHANGE_MANIFEST]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "upgrade_guide": {
    "version": "[TARGET_VERSION]",
    "pre_flight_checks": [
      {
        "check_id": "string",
        "description": "string",
        "command_or_query": "string",
        "expected_result": "string",
        "failure_action": "string"
      }
    ],
    "ordered_steps": [
      {
        "step_number": integer,
        "category": "configuration | database_migration | api_change | dependency_update | data_migration | other",
        "breaking_change_reference": "string (must match an ID from the manifest)",
        "action": "string (clear imperative instruction)",
        "before_example": "string (code or config before)",
        "after_example": "string (code or config after)",
        "verification": "string (how to confirm the step succeeded)",
        "rollback": "string (how to undo this step if verification fails)"
      }
    ],
    "post_migration_checks": [
      {
        "check_id": "string",
        "description": "string",
        "command_or_query": "string",
        "expected_result": "string"
      }
    ],
    "completeness_report": {
      "total_breaking_changes_in_manifest": integer,
      "steps_generated": integer,
      "uncovered_breaking_change_ids": ["string"]
    }
  }
}

## CONSTRAINTS

- Every breaking change in the manifest must be addressed by at least one step. If a breaking change cannot be addressed with a step, list it in uncovered_breaking_change_ids with an explanation.
- Steps must be ordered by dependency: configuration changes before migrations, migrations before code changes, all pre-flight checks before any step.
- Use exact field names, command flags, and configuration keys from the manifest. Do not invent or guess.
- If the manifest lacks sufficient detail for a step, mark that step with a [NEEDS_CLARIFICATION] prefix and explain what is missing.
- Rollback instructions must be complete and reversible. If a step is not reversible, state that explicitly and recommend a backup before proceeding.
- Do not include steps for non-breaking changes, feature additions, or bug fixes unless they are prerequisites for a breaking change step.

## EXAMPLES

[FEW_SHOT_EXAMPLES]

## RISK LEVEL

[RISK_LEVEL: low | medium | high | critical]

If RISK_LEVEL is high or critical, add a prominent warning block at the top of the guide recommending a staging environment dry-run before production execution.

Adapt this template by replacing the square-bracket placeholders with your data. The [BREAKING_CHANGE_MANIFEST] should be a structured JSON or YAML object containing each breaking change with a unique ID, description, affected surfaces, and before/after signatures. The [FEW_SHOT_EXAMPLES] placeholder should contain one or two complete input-output pairs showing the expected mapping from manifest entries to ordered steps. If you omit examples, the model may produce plausible but incorrectly ordered steps. The [RISK_LEVEL] placeholder accepts one of four values and gates whether a staging dry-run warning is prepended to the output. Always validate the output against the schema before publishing. If the completeness_report shows uncovered breaking changes, route the output to a human reviewer or trigger a repair prompt that asks the model to fill the gaps with explicit [NEEDS_CLARIFICATION] markers.

The upgrade instructions prompt is designed to run after breaking change detection and schema impact analysis have completed. It consumes a structured list of breaking changes, deprecated surfaces, and configuration modifications, then produces ordered step-by-step upgrade procedures. In a production pipeline, this prompt should execute as a post-release-candidate step—after diffs are analyzed but before the release note is published. The prompt expects a JSON array of breaking changes as [BREAKING_CHANGES], each containing the affected surface, severity, and migration notes from prior analysis steps. Do not feed raw diffs directly into this prompt; it assumes pre-processed, categorized breaking changes.

Wire the prompt into your CI/CD workflow using a dedicated job that runs after the breaking change detection step. The job should: (1) load the breaking change manifest from the previous step's artifact, (2) inject it into the [BREAKING_CHANGES] placeholder along with the [RELEASE_VERSION] and [MIGRATION_WINDOW] variables, (3) call the model with response_format set to the defined JSON schema for ordered upgrade steps, (4) validate the output against the schema—each step must have a step_number, action, affected_component, pre_flight_check, and rollback_action field, (5) run a completeness check: every breaking change in the input must map to at least one upgrade step in the output, and (6) if validation fails, retry once with the validation errors appended to the [CONSTRAINTS] block. Use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set temperature to 0.1–0.2 for deterministic, repeatable results.

For high-risk releases—major version bumps, database migrations, or auth changes—route the generated upgrade instructions to a human review queue before publication. The review step should verify that pre-flight checks are complete (backup instructions, downtime estimates, rollback commands) and that no breaking change is silently omitted. Log every generation attempt with the input manifest hash, output step count, validation errors, and reviewer decision. Avoid running this prompt on every commit; trigger it only on release candidate tags or merged release PRs to control cost and noise. If the prompt produces fewer steps than the number of breaking changes, treat it as a failure and escalate—do not silently publish incomplete upgrade instructions.