Dependency Graph Impact Analysis Prompt

This prompt is designed for maintainers and build engineers who need to evaluate a specific dependency upgrade before merging it into the main branch. The core job-to-be-done is producing a structured, risk-scored impact report that maps the full blast radius of a version change. You should use this prompt when you have a concrete package to upgrade, access to the repository's dependency manifest (e.g., package.json, Cargo.toml) and lockfile, and the ability to resolve the actual import graph. The ideal output is not a generic changelog summary but a surgical analysis that traces every affected package, transitive dependent, and API surface change back to a real import or call site in your codebase.

To get a reliable report, you must provide the model with the exact package name, the current and target versions, and the raw content of your dependency manifest and lockfile. The prompt is most effective when you also supply a pre-computed dependency graph or a tool that allows the model to query it. Without this data, the model will be forced to hallucinate dependency relationships, which renders the risk scores useless. The prompt includes placeholders like [DEPENDENCY_GRAPH] and [LOCKFILE_CONTENT] specifically to enforce this data grounding. You should also set a [RISK_LEVEL] threshold to filter out low-impact noise, ensuring the report focuses on modules that actually require human review and testing.

Do not use this prompt for general code review, diagnosing a failing build, or when you lack the actual import graph data. It is also the wrong tool if you are simply curious about a package's changelog; this prompt is for active upgrade evaluation. Before running it, ensure you have a way to validate the output. A critical next step is to run an eval that verifies every claimed impact traces to a real file path and import statement. If the model cannot ground a finding in the provided graph or manifest, treat that section of the report as a hallucination and remove it before sharing with the team.

This prompt template is designed to be pasted directly into your AI coding agent or LLM interface. It instructs the model to act as a build engineer and produce a structured impact analysis report for a proposed dependency upgrade. The model is expected to reason across the full dependency graph, identify affected packages and API surfaces, and assign risk scores based on actual import and call-site evidence.

codeCopy
You are a senior build engineer analyzing a dependency upgrade.

Your task is to produce a Dependency Graph Impact Analysis Report for the upgrade described below.

## Inputs
- [PACKAGE_NAME]: The name of the package being upgraded.
- [CURRENT_VERSION]: The currently installed version.
- [TARGET_VERSION]: The proposed new version.
- [CHANGELOG]: The full changelog or release notes between [CURRENT_VERSION] and [TARGET_VERSION].
- [DEPENDENCY_GRAPH]: A representation of the project's full dependency graph, including direct and transitive dependents of [PACKAGE_NAME].
- [REPOSITORY_CONTEXT]: Relevant source files, import statements, and API usage examples for [PACKAGE_NAME] within the project.

## Constraints
- [CONSTRAINTS]:
  - Every claimed impact must be traceable to a specific import or call site in [REPOSITORY_CONTEXT].
  - Do not invent breaking changes not present in [CHANGELOG].
  - If information is insufficient to determine impact, mark it as "Uncertain" and state what is missing.

## Output Schema
Produce a JSON object conforming to this [OUTPUT_SCHEMA]:
{
  "upgrade_summary": {
    "package": "string",
    "from_version": "string",
    "to_version": "string",
    "risk_level": "LOW | MEDIUM | HIGH | CRITICAL",
    "recommendation": "PROCEED | PROCEED_WITH_CAUTION | DELAY | REJECT"
  },
  "breaking_changes": [
    {
      "change_description": "string",
      "severity": "LOW | MEDIUM | HIGH",
      "affected_files": ["string"],
      "migration_action": "string"
    }
  ],
  "affected_modules": [
    {
      "module_path": "string",
      "dependency_type": "DIRECT | TRANSITIVE",
      "risk_score": "number (1-10)",
      "impact_rationale": "string",
      "recommended_test_order": "number"
    }
  ],
  "transitive_dependents": ["string"],
  "test_plan": {
    "recommended_order": ["string"],
    "critical_tests": ["string"],
    "regression_risk_areas": ["string"]
  },
  "uncertainties": ["string"]
}

To adapt this template, replace each square-bracket placeholder with the actual data from your repository. The [DEPENDENCY_GRAPH] can be a parsed package-lock.json, yarn.lock, Cargo.lock, or output from a tool like npm ls --all. The [REPOSITORY_CONTEXT] should be a grep or static analysis dump showing how the target package is used. For high-risk upgrades, always route the final report for human review before merging any automated PR. A common failure mode is the model hallucinating API changes not present in the changelog; mitigate this by strictly enforcing the constraint that every finding must cite evidence from the provided [CHANGELOG] or [REPOSITORY_CONTEXT].

This prompt is designed to be called programmatically as part of a dependency update review workflow, not as a one-off chat interaction. The typical integration point is a CI job triggered by a Dependabot/Renovate PR or a manual dep-review CLI command. The harness must supply structured inputs—the package name, current and target versions, a parsed dependency graph (from npm ls --json, pipdeptree --json, or equivalent), and the repository's import/call-site search results—so the model has grounded data to analyze rather than hallucinating from training memory.

Input assembly: Before calling the prompt, the harness should: (1) extract the full transitive dependency graph from the lockfile; (2) run a grep or static analysis pass to find every file that imports or calls the affected package; (3) fetch the changelog or release notes for the target version; (4) diff the package's exported API surface between versions if available. These become the [DEPENDENCY_GRAPH], [AFFECTED_FILES], [CHANGELOG], and [API_DIFF] placeholders. Model selection: Use a model with strong structured output support and a large context window (GPT-4o, Claude 3.5 Sonnet, or equivalent) since dependency graphs can be large. For smaller graphs, a fast model like Claude 3 Haiku with constrained output works. Validation layer: The harness must validate the JSON output against a schema that requires every affected_module to reference a real file path present in [AFFECTED_FILES], every risk_score to be an integer 1-10, and every recommended_test_order entry to map to an existing test target. Reject outputs that cite files or packages not present in the input graph.

Retry and fallback: If validation fails, retry once with the validation errors injected as [PREVIOUS_ERRORS] in the prompt. If the second attempt also fails, fall back to a deterministic static analysis path (e.g., npm outdated + grep for imports) and flag the PR for mandatory human review. Human review gate: For high-risk upgrades (semver major, security patches, or risk_score >= 7 on any module), the harness should post the impact report as a PR comment and block merge until a maintainer approves. The report should include a clear review_required: true field and a summary suitable for a PR comment. Logging: Log the prompt version, model, input sizes, validation pass/fail, and review decision for auditability. This makes it possible to tune the prompt over time and detect drift in model behavior across dependency review runs.