Breaking Change Detection and Migration Guidance Prompt Template

This prompt is designed for release managers, platform engineers, and technical leads who need to systematically identify breaking changes from raw commit diffs, changelogs, or API specification deltas. The job-to-be-done is converting unstructured or semi-structured change data into a categorized, actionable migration guide that downstream consumers can execute. The ideal user has access to source material such as git diff output between two release tags, an OpenAPI specification diff, or a structured changelog from a project management tool. They need to produce entries that include before/after code comparisons, explicit migration steps, and effort estimates so that teams consuming the API or library can plan their upgrades without reading every commit.

Use this prompt when you have concrete source material that contains the actual changes—never rely on the model's parametric knowledge of a library or API, as that knowledge may be outdated or hallucinated. The prompt requires several inputs to be effective: [SOURCE_DIFF] containing the raw text of code or specification changes, [RELEASE_CONTEXT] specifying the old and new version identifiers, and [CONSUMER_PROFILE] describing the typical user of the API (e.g., 'frontend developers using a React SDK' or 'backend services calling a REST API'). Optionally, provide [KNOWN_BREAKING_CHANGES] as a list of changes you already suspect are breaking, which helps the model calibrate its detection threshold. Do not use this prompt for additive feature documentation, internal refactoring notes that don't affect public surfaces, or routine dependency bumps where the upstream changelog is the authoritative source.

The prompt is not a replacement for human review. Breaking change detection has asymmetric risk: a false negative (missing a breaking change) causes production incidents for consumers, while a false positive wastes engineering time on unnecessary migration work. Always pair this prompt with evaluation checks that measure both recall against a known set of breaking changes and precision against a set of non-breaking changes. Before shipping the generated migration guide, have an engineer who worked on the changes review every entry for accuracy. For high-risk releases, run the prompt against multiple models and diff the outputs to surface disagreements that require human judgment.

This prompt template is designed to be copied directly into your AI harness. It accepts a commit diff, changelog draft, or API specification delta and outputs a structured list of breaking changes. Each entry includes a before/after code comparison, step-by-step migration guidance, and an estimated effort level. The template uses square-bracket placeholders for all variable inputs, making it straightforward to wire into a CI/CD pipeline, release automation script, or documentation workflow.

textCopy
You are a release engineering assistant specialized in detecting breaking changes from software diffs and changelogs. Your task is to analyze the provided input and produce a structured, categorized list of breaking changes with migration guidance.

## INPUT
[DIFF_OR_CHANGELOG]

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "breaking_changes": [
    {
      "category": "API | Schema | Config | Dependency | Behavior | Deprecation",
      "severity": "critical | major | minor",
      "summary": "One-sentence description of what broke",
      "affected_surface": "Function name, endpoint path, table name, or config key",
      "before": "Code or configuration example before the change",
      "after": "Code or configuration example after the change",
      "migration_steps": ["Ordered list of actions a consumer must take"],
      "effort_estimate": "trivial | low | medium | high",
      "effort_rationale": "Why this effort level was assigned",
      "false_positive_risk": "low | medium | high",
      "false_positive_note": "Conditions under which this might not be a real breaking change"
    }
  ],
  "non_breaking_notable_changes": [
    {
      "summary": "Description of a notable but non-breaking change",
      "reason_not_breaking": "Why this does not require consumer action"
    }
  ],
  "analysis_confidence": "high | medium | low",
  "confidence_rationale": "Explanation of overall confidence level"
}

## CONSTRAINTS
- Only flag a change as breaking if existing consumer code, configuration, or integration would fail or produce incorrect results without modification.
- Do not flag additive features, new optional parameters, or backward-compatible deprecations as breaking.
- For each breaking change, provide a concrete before/after example. If the diff does not contain enough context to construct examples, set false_positive_risk to "high" and explain what additional context is needed.
- If a change is a deprecation with a future removal date, classify it as breaking only if the removal date has passed or is within [DEPRECATION_WINDOW_MONTHS] months.
- Exclude changes that only affect internal implementation details not exposed to consumers.
- If no breaking changes are detected, return an empty breaking_changes array with high confidence and a brief rationale.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK_LEVEL
[HIGH_RISK_DOMAINS]

## INSTRUCTIONS
1. Parse the input to identify all changes.
2. For each change, determine if it is breaking using the constraints above.
3. Categorize each breaking change and assign severity.
4. Construct before/after examples from the diff context.
5. Write migration steps in imperative form, ordered by required sequence.
6. Assign effort estimates with rationale.
7. Flag any uncertain classifications with false_positive_risk and explanatory notes.
8. Return only the JSON object. Do not include any text outside the JSON.

To adapt this template, replace each square-bracket placeholder with your actual data. [DIFF_OR_CHANGELOG] should contain the raw diff output, changelog draft, or OpenAPI specification delta. [DEPRECATION_WINDOW_MONTHS] sets your team's policy for when a deprecation becomes a breaking change—typically 3 to 6 months. [FEW_SHOT_EXAMPLES] should include 2–3 annotated examples of breaking vs. non-breaking changes from your codebase to calibrate the model's judgment. [HIGH_RISK_DOMAINS] should list areas where false negatives are unacceptable, such as authentication, billing, or data integrity surfaces. For these domains, always route outputs to human review before publication. After copying the template, test it against a known release with documented breaking changes and compare the model's output to your manually curated list. Flag any missed breaking changes or false positives and add them to [FEW_SHOT_EXAMPLES] for the next run.

This prompt is designed to sit inside a CI/CD or release management workflow, not as a one-off chat interaction. The typical integration point is after commit diffs or changelog drafts are available but before the release is published. Feed the prompt a structured diff (e.g., git diff v1.0..v2.0 -- unified) or a raw changelog draft, along with the previous stable API surface as [CONTEXT]. The output is a structured JSON array of breaking changes, each with before/after code snippets, migration steps, and an effort estimate. This output should be treated as a candidate list requiring human review, not as a final artifact.

Validation is the critical next step. Parse the model's JSON output and run it through a schema validator that checks for required fields (breaking_change_description, before_code, after_code, migration_steps, effort_estimate, affected_surfaces). If validation fails, retry the prompt once with the validation errors appended to [CONSTRAINTS] as explicit fix instructions. For high-risk releases (e.g., security patches, database migrations), route the validated output to a human approval queue before it reaches the public changelog. Log the raw prompt, the model response, and the validation result for auditability. Model choice matters here: use a model with strong code-diff reasoning and structured output support, such as gpt-4o or claude-3.5-sonnet, and set response_format to json_object where available.

Avoid wiring this prompt directly to an automated publish step without human review. False positives (flagging additive changes as breaking) and false negatives (missing subtle signature changes) are both common failure modes. Implement a companion eval step: maintain a golden dataset of known breaking and non-breaking changes, run the prompt against it on each prompt revision, and gate deployment on recall ≥ 0.90 and precision ≥ 0.85. If the prompt starts over-flagging deprecation warnings as breaking changes, adjust [CONSTRAINTS] to clarify the distinction. The next step after reading this section is to copy the prompt template, define your input schema, and build the validation harness before integrating it into your release pipeline.