Breaking Change Detection Prompt for Package Manifests

This prompt is designed for a developer or platform engineer who is staring at a dependency update pull request and needs to know, with precision, whether merging it will break production. Its job-to-be-done is not to provide a general risk score or a vague compatibility guess. Instead, it performs a targeted comparison: it takes the upstream package's documented breaking changes—extracted from a changelog, release notes, or API diff—and cross-references them against a concrete report of how your codebase actually imports and calls that package. The output is a migration impact list that maps each breaking change to the specific files, functions, and call sites in your repository that are affected. This turns an abstract upstream warning into an actionable, codebase-specific remediation checklist.

To use this prompt effectively, you must provide two grounded inputs. The first is the upstream change evidence, such as a [CHANGELOG_DIFF] or [API_DIFF] that explicitly documents deprecated functions, removed methods, changed signatures, altered return types, or modified default behaviors. The second is a [CODEBASE_USAGE_REPORT], typically generated by a grep, rg, or static analysis tool, that shows every import statement, function call, class instantiation, or type reference your codebase makes against that package. Without both inputs, the prompt cannot perform its core function and will either hallucinate usage or miss critical breakages. This prompt is not a speculative compatibility guesser; it requires grounding against real import usage. It is also not a replacement for running your test suite or performing a canary deployment. Use it as a pre-merge review accelerator that focuses human attention on the highest-risk call sites before CI even runs.

There are clear situations where this prompt is the wrong tool. Do not use it when you lack a precise changelog or API diff—if the upstream maintainer only provides a vague 'bug fixes and improvements' note, the prompt has no evidence to work with and will produce unreliable output. Do not use it to assess transitive dependencies whose code you do not directly import; the codebase usage report will show no direct calls, creating a false sense of safety. Do not use it for runtime behavioral changes that are not surfaced in the API surface, such as performance regressions, memory profile changes, or subtle algorithm modifications. Finally, do not treat its output as a final approval gate. The prompt identifies syntactic and structural breakage risks, but it cannot verify semantic correctness. A function signature may remain compatible while its behavior changes in a way that corrupts data. Always pair this prompt's output with a targeted test run against the identified call sites and, for high-risk updates, a human review of the behavioral changelog entries.

This prompt template is designed to be filled programmatically from your package manager, static analysis tooling, and changelog sources before being sent to the model. The goal is not to summarize the changelog, but to produce a migration impact list that maps each breaking change to the specific files and call sites in your codebase that are affected. Replace every [PLACEHOLDER] with data extracted from your CI pipeline or local toolchain. The prompt instructs the model to ground every finding in the provided usage evidence and to abstain when a changelog entry cannot be matched to actual code.

textCopy
You are a dependency update reviewer. Your task is to detect breaking changes in a package update and map them to affected call sites in the codebase.

## PACKAGE UPDATE
- Package: [PACKAGE_NAME]
- Current version: [CURRENT_VERSION]
- Target version: [TARGET_VERSION]
- Release type (major/minor/patch): [RELEASE_TYPE]

## CHANGELOG OR RELEASE NOTES
[CHANGELOG_TEXT]

## CODEBASE USAGE REPORT
This report maps every import from [PACKAGE_NAME] to the files and symbols used.
[USAGE_REPORT]

## INSTRUCTIONS
1. Parse the changelog for entries marked as breaking changes, removals, deprecated APIs, changed defaults, or behavioral modifications.
2. For each breaking change, search the usage report for affected imports, function calls, class instantiations, or configuration usage.
3. If a breaking change has no matching usage in the codebase, mark it as **No Impact** and explain why.
4. If a breaking change matches usage, produce a finding with:
   - **Severity**: BLOCKER (will cause build/runtime failure), HIGH (behavioral change, likely regression), MEDIUM (deprecation, future risk), LOW (cosmetic or unlikely to affect this codebase).
   - **Affected files**: List file paths and line ranges from the usage report.
   - **Migration action**: A specific, actionable step the developer must take.
   - **Evidence**: Quote the relevant changelog line and the matching usage line.
5. If the changelog is ambiguous or the usage report is incomplete, state your confidence as LOW and recommend manual review.
6. Do not invent usage that is not in the usage report. Do not guess about internal package behavior not described in the changelog.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "package": "string",
  "version_change": "string",
  "breaking_changes_detected": number,
  "findings": [
    {
      "severity": "BLOCKER | HIGH | MEDIUM | LOW",
      "changelog_entry": "string",
      "affected_files": ["file_path:line_range"],
      "migration_action": "string",
      "evidence": "string",
      "confidence": "HIGH | MEDIUM | LOW"
    }
  ],
  "no_impact_entries": [
    {
      "changelog_entry": "string",
      "reason_no_impact": "string"
    }
  ],
  "recommendations": ["string"],
  "overall_risk": "BLOCKER | HIGH | MEDIUM | LOW",
  "requires_manual_review": boolean
}

Adaptation guidance: The [USAGE_REPORT] placeholder is the most critical input. Generate it by running a static analysis tool (such as grep, rg, ast-grep, or a language server) to find every import of [PACKAGE_NAME] and the specific symbols, function calls, or class references used. For JavaScript/TypeScript, include require() and import statements with their containing file and line. For Python, include import and from ... import statements. The quality of the model's output depends entirely on the completeness of this usage report. If your toolchain cannot produce a reliable usage report, set [USAGE_REPORT] to a clear statement of limitation and expect the model to return "confidence": "LOW" with "requires_manual_review": true. Always run this prompt in a CI context where the changelog can be fetched from the registry or repository, not from a cached or user-provided source.

This prompt is designed to run inside a CI job triggered by a dependency update pull request. The harness should extract the package manifest diff (e.g., package.json, requirements.txt, Cargo.toml), the corresponding lock file changes, and a static analysis of import usage across the codebase. Feed these as [MANIFEST_DIFF], [LOCKFILE_DIFF], and [IMPORT_USAGE] respectively. The prompt also requires [CHANGELOG_ENTRIES] for the updated packages—pull these from the registry API or a local cache, not from the PR description, to avoid hallucination-prone summaries. The [CODEBASE_LANGUAGE] and [PACKAGE_ECOSYSTEM] variables constrain the model's reasoning to the correct semantic versioning conventions and import resolution rules.

Validation is critical because a false negative here can ship a breaking change to production. After the model returns its JSON output, run a structural validator that checks: (1) every affected_call_site references a file path and line number present in the diff, (2) every breaking_change entry cites a specific changelog line or API signature change, and (3) the migration_impact severity is one of the allowed enum values. If validation fails, retry once with the validation errors appended to [CONSTRAINTS] as explicit negative feedback. If the second attempt also fails, fail the CI check open and post a comment on the PR requesting manual review. Log every prompt version, model, input hash, and validation result for auditability. For high-risk packages (major version bumps, security-critical libraries), add a human approval gate that blocks merge until a designated reviewer acknowledges the breaking change report.

Model choice matters here. Use a model with strong code reasoning and long-context handling, since changelogs and lock file diffs can be large. Claude 3.5 Sonnet or GPT-4o are good defaults. Avoid smaller or older models that may miss subtle API surface changes. Set temperature to 0 or very low (0.1) to maximize deterministic output. If your CI budget is tight, cache the prompt prefix containing the system instruction and output schema, since those are static across runs. The dynamic portion is the diff and changelog data. For teams using RAG, you can pre-index package changelogs and retrieve only the relevant sections rather than passing the full changelog, but ensure the retrieval step doesn't silently drop breaking change notices buried in minor release notes. Finally, wire the structured output into your PR comment or review system so developers see the migration impact list directly in their workflow, not buried in CI logs.