Breaking Change Detection Prompt for Package Updates

This prompt is designed for a developer or build engineer who is reviewing a dependency update—typically a pull request from Dependabot, Renovate, or a manual version bump—and needs to understand the breaking changes before merging. The job-to-be-done is not just to list changes from a changelog, but to produce a categorized, severity-ranked, and codebase-grounded impact analysis. The ideal user has access to the package's changelog or release notes, the diff of the dependency manifest, and the repository's own source code. The prompt assumes the model can search or read the codebase to verify whether a breaking change actually affects any call sites.

Use this prompt when the cost of a breaking change slipping into production is high—for example, in shared libraries, API services, or monorepos where a silent API break can cascade across multiple teams. It is particularly valuable when the changelog is long, when the version jump spans multiple major releases, or when the package has a history of undocumented breaking changes. The prompt forces the model to ground every claimed impact in actual codebase evidence, which reduces false positives and prevents unnecessary migration work. It also requires the model to propose concrete migration actions, not just flag problems.

Do not use this prompt for trivial patch updates where the changelog is empty or contains only bug fixes with no API surface changes. It is also inappropriate for initial dependency addition (where there is no existing usage to analyze) or for packages where the source code of the dependency itself is the primary artifact and the changelog is not available. If the repository has no existing imports of the package, the prompt will correctly report zero impact, but a simpler check would suffice. For high-risk production deployments, always pair the model's output with a human review step and, where possible, automated test execution against the actual upgrade before merging.

This prompt template is designed to be dropped into an AI coding agent or review workflow. It instructs the model to analyze a dependency changelog or diff against your actual repository usage and produce a structured, actionable report. The square-bracket placeholders let you inject the specific package, version range, changelog content, and repository context without rewriting the core logic. Use this as the foundation for a tool-calling agent where the model can request file contents or grep results to ground its analysis.

textCopy
You are a build and dependency analyst. Your task is to review a package update and identify breaking changes that could affect the repository.

## INPUTS
- Package: [PACKAGE_NAME]
- Current version: [CURRENT_VERSION]
- Target version: [TARGET_VERSION]
- Changelog or release notes: [CHANGELOG_CONTENT]
- Repository API usage (imports, calls, type references): [REPO_USAGE_SNIPPETS]

## CONSTRAINTS
- Classify each finding as BREAKING, POTENTIALLY_BREAKING, or NON_BREAKING.
- A change is BREAKING only if it directly affects a code path present in [REPO_USAGE_SNIPPETS].
- A change is POTENTIALLY_BREAKING if it could affect the repository but usage cannot be confirmed from the provided snippets.
- Do not classify a change as breaking based on changelog language alone. You must ground every BREAKING classification in a specific import, call site, or type reference from [REPO_USAGE_SNIPPETS].
- If [REPO_USAGE_SNIPPETS] is empty or insufficient, request the missing information using the available tools before producing the final report.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "package": "string",
  "version_change": {
    "from": "string",
    "to": "string"
  },
  "breaking_changes": [
    {
      "severity": "BREAKING | POTENTIALLY_BREAKING",
      "change_description": "string",
      "affected_code_paths": ["string"],
      "migration_action": "string",
      "grounding_evidence": "string"
    }
  ],
  "non_breaking_notes": ["string"],
  "recommended_action": "UPGRADE_SAFE | UPGRADE_WITH_MIGRATION | HOLD_AND_REVIEW",
  "confidence": "HIGH | MEDIUM | LOW"
}

## RISK LEVEL
- If any BREAKING change is found, set recommended_action to UPGRADE_WITH_MIGRATION or HOLD_AND_REVIEW.
- If confidence is LOW, recommend HOLD_AND_REVIEW and request human review.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## TOOLS
You have access to the following tools to gather additional repository context:
[AVAILABLE_TOOLS]

Adaptation guidance: Replace each placeholder with concrete values from your CI pipeline or review tool. The [REPO_USAGE_SNIPPETS] placeholder should be populated by a grep or code-search tool that extracts every import, require, or reference to the target package. If you are wiring this into an agent, map [AVAILABLE_TOOLS] to your actual tool definitions (e.g., file read, grep, AST search). The [FEW_SHOT_EXAMPLES] placeholder should contain 2-3 annotated examples showing correct classification of breaking vs. non-breaking changes with grounding evidence. Start with one example where a removed function is correctly flagged because it appears in the codebase, and one where a changelog mentions a breaking change that does not affect the repository and is correctly classified as NON_BREAKING.

Before shipping: Validate the output against a golden set of known package updates where you have manually verified the breaking changes. Run the prompt against at least 10 real-world updates and measure false positive rate (non-breaking changes misclassified as breaking) and false negative rate (breaking changes missed). If false positives exceed 15%, tighten the grounding requirement by adding explicit instructions that every BREAKING classification must include a direct code reference. If false negatives exceed 5%, expand the [REPO_USAGE_SNIPPETS] extraction to cover more reference patterns (e.g., type annotations, re-exports, dynamic imports). Always require human review for any update classified as UPGRADE_WITH_MIGRATION or HOLD_AND_REVIEW before merging.

This prompt is designed to operate as a gated analysis step within a dependency update workflow, not as a standalone chatbot query. The typical integration point is a pull request opened by Dependabot, Renovate, or a manual package.json bump. The harness must supply the prompt with three concrete inputs: the full changelog or release notes for the target version range, a repository-wide grep of actual API usage (imports, method calls, type references), and the diff of the lockfile or manifest change. Without these three inputs grounded in the real repository, the model will hallucinate affected code paths or misclassify non-breaking changes as breaking. The prompt expects these inputs to be populated into the [CHANGELOG], [USAGE_GREP], and [LOCKFILE_DIFF] placeholders respectively.

Validation and retry logic is critical because false positives erode trust in automated dependency review. After the model returns its categorized list of breaking changes, a post-processing validator must cross-reference every claimed affected file path against the actual repository tree. If a reported path does not exist, the finding should be discarded or flagged for human review. For high-severity findings, implement a dual-model verification pattern: run the same prompt against a second model (or a different temperature setting) and compare the severity classifications. Findings that disagree between runs should be surfaced to a human reviewer rather than automatically blocking a merge. Log every prompt execution with its inputs, outputs, and validation results to enable retrospective analysis when a breaking change slips through.

Model choice and latency considerations matter here because this prompt runs on every dependency update PR, which can be dozens per week in active repositories. Use a fast, cost-efficient model for the initial triage pass (such as Claude Haiku or GPT-4o-mini) and reserve a more capable model for escalation when the initial pass flags high-severity items or when validation fails. The prompt does not require tool use or retrieval-augmented generation because all evidence is supplied inline, but you should implement a caching layer that stores results keyed by the tuple of (package name, from version, to version, repository commit hash). This prevents re-running the same analysis when multiple PRs touch the same dependency or when a PR is rebased. Finally, wire the output into your CI status check: a green checkmark when no breaking changes are detected, a yellow warning with a summary table for medium-severity items, and a red block with required human approval for high-severity findings.