Dependency Update Impact Review Prompt

Platform teams and engineering leads face a constant stream of automated dependency bumps from tools like Dependabot or Renovate. Manual review of every update does not scale, but skipping review introduces breaking changes, security vulnerabilities, and subtle API incompatibilities. This prompt automates the initial triage of a dependency update by analyzing the package diff and changelog to produce a structured upgrade advisory. Use it in CI/CD pipelines to gate automated merges, as a pre-review checklist for developers, or as a first-pass filter that escalates only high-risk updates for human approval. The prompt is designed for a single dependency update at a time and assumes you have the diff and changelog available as input.

The ideal user is a platform engineer or tech lead responsible for maintaining dependency hygiene across multiple repositories. The prompt requires two concrete inputs: the raw unified diff of the dependency change and the corresponding changelog or release notes. It works best for libraries and frameworks where breaking changes are documented, such as major version bumps of open-source packages. Do not use this prompt for transitive dependency updates where no direct changelog is available, for monorepo-wide batch updates that span dozens of packages, or for infrastructure dependencies like database version upgrades where the impact surface extends beyond code into runtime configuration and data integrity.

Before wiring this into an automated merge gate, run it against a set of known dependency updates where you already know the outcome—both safe patches and breaking major versions—to calibrate the model's risk classification against your team's actual tolerance. The prompt produces a structured advisory, not a binary approve/reject decision. Always require human review for updates flagged as high risk, and log the advisory alongside the merge commit for auditability.

This template is the core engine for automated dependency update review. It is designed to be pasted directly into your AI harness, where you replace the square-bracket placeholders with data from your package manager, CI pipeline, and repository. The prompt instructs the model to act as a senior platform engineer, cross-referencing the raw diff and changelog against your actual codebase usage to produce a structured, risk-ranked advisory. Before using this in production, ensure you have a validation step that checks the output JSON schema and a human-in-the-loop rule for any finding marked severity: critical.

textCopy
You are a senior platform engineer reviewing an automated dependency update. Your task is to analyze the provided dependency update diff and changelog to assess the risk of merging this update into the main branch. You must produce a structured upgrade advisory in JSON format.

## Input Data
- **Dependency Name:** [DEPENDENCY_NAME]
- **Current Version:** [CURRENT_VERSION]
- **Proposed Version:** [PROPOSED_VERSION]
- **Package Manager:** [PACKAGE_MANAGER]
- **Update Diff:**
  ```diff
  [RAW_DEPENDENCY_DIFF]

• Changelog:

  markdownCopy
  [RAW_CHANGELOG]

• Codebase Usage Context:
  • Direct Import Paths: [LIST_OF_IMPORT_PATHS]
  • Affected Files: [LIST_OF_AFFECTED_FILE_PATHS]
  • Existing Test Files: [LIST_OF_TEST_FILE_PATHS]

Analysis Constraints

• Classify breaking changes strictly according to semantic versioning principles relative to the [CURRENT_VERSION].
• Only flag an API usage as impacted if a changed or removed symbol is directly imported or called in the provided codebase context.
• Assess test coverage adequacy by checking if the affected files have corresponding test files with relevant test cases for the changed APIs.
• If the changelog mentions a security fix, its severity must be at least high.

Output Schema

Return ONLY a valid JSON object with the following structure. Do not include any text outside the JSON object.

jsonCopy
{
  "advisory": {
    "dependency": "string",
    "current_version": "string",
    "proposed_version": "string",
    "overall_risk_score": "low|medium|high|critical",
    "summary": "A concise, one-sentence summary of the primary risk or benefit."
  },
  "breaking_changes": [
    {
      "change_description": "string",
      "source": "changelog|diff",
      "severity": "low|medium|high|critical",
      "our_code_impacted": true|false,
      "impacted_files": ["string"],
      "migration_notes": "string or null"
    }
  ],
  "security_advisories": [
    {
      "cve_id": "string or null",
      "description": "string",
      "severity": "high|critical",
      "our_code_impacted": true|false
    }
  ],
  "test_coverage_gaps": [
    {
      "affected_api": "string",
      "existing_test_files": ["string"],
      "gap_description": "string",
      "recommended_test": "string"
    }
  ],
  "recommendation": {
    "action": "merge|hold|reject",
    "reasoning": "A brief paragraph explaining the recommendation based on the analysis."
  }
}

To adapt this template, start by replacing the [RAW_DEPENDENCY_DIFF] and [RAW_CHANGELOG] placeholders with the actual text output from your package manager or dependency bot. The [LIST_OF_IMPORT_PATHS] and [LIST_OF_AFFECTED_FILE_PATHS] fields are critical for grounding the analysis in your specific codebase; a simple grep for the dependency name in your project can populate these. For high-risk updates, consider adding a [CONSTRAINTS] block that forces a hold recommendation if any critical severity finding is present. Always run the model's JSON output through a schema validator before posting it as a comment on the PR to prevent malformed data from breaking your CI pipeline.

This prompt is designed to run automatically on every Dependabot, Renovate, or manual dependency bump PR. The harness should trigger on pull request events where the diff is dominated by package manifest and lock file changes (e.g., package.json, package-lock.json, Cargo.toml, Cargo.lock, go.mod, go.sum, requirements.txt). The primary integration point is a CI job that checks out the PR branch, extracts the dependency diff and changelog, calls the LLM, validates the structured output, and posts the result as a PR comment or status check. Do not gate merge solely on the AI output; use it as an advisory signal that helps reviewers decide whether the upgrade needs deeper manual investigation.

The harness must assemble two inputs before calling the prompt: the dependency diff (filtered to only manifest and lock file changes) and the changelog or release notes for the updated package version. For the diff, use git diff origin/main...HEAD -- package.json package-lock.json or equivalent. For the changelog, query the package registry API (npm, PyPI, crates.io) or parse the CHANGELOG.md from the updated package's repository. If the changelog is unavailable, set [CHANGELOG] to 'No changelog available' and expect the model to flag this as a risk factor. The harness should enforce a maximum diff size (e.g., 500 lines) and maximum changelog length (e.g., 2000 words) to stay within context windows and control latency. If the diff exceeds the limit, truncate with a note and flag the review as partial.

Validation and retries: Parse the model's JSON output and validate it against a strict schema. Required fields include breaking_change_risk (enum: low, medium, high, critical), api_usage_impact (array of affected files and symbols), test_coverage_assessment (object with adequate, gaps, and recommended_tests), and upgrade_advisory (enum: safe_to_merge, proceed_with_caution, manual_review_required, do_not_merge). If validation fails, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the retry also fails, post a comment indicating the automated review could not be completed and flag for manual review. Model choice: Use a model with strong code reasoning capabilities (e.g., Claude 3.5 Sonnet, GPT-4o) and set temperature=0 for deterministic, repeatable assessments. Logging: Record the prompt version, model, input hashes, output, validation status, and review decision for auditability. This trace is essential when a dependency upgrade later causes a production incident and the team needs to understand what the automated review did or did not catch.

Human approval integration: For upgrades where the model returns breaking_change_risk: critical or upgrade_advisory: do_not_merge, the harness should block auto-merge and require a human reviewer to acknowledge the advisory. For lower-risk upgrades, the harness can post the structured review as a PR comment with a clear summary and let the team's existing review process decide. Do not treat the AI review as a replacement for human judgment on critical paths—dependency upgrades can introduce subtle runtime changes that static diff analysis alone cannot detect. The harness should also track whether the model's advisory was overridden by a human reviewer, creating a feedback loop for evaluating the prompt's accuracy over time.