Chain-of-Thought Dependency Resolution Prompt for Package Updates

This prompt is for developers and platform engineers who need to upgrade a core package and must reason through the resulting cascade of transitive dependency conflicts, breaking API changes, and peer dependency mismatches. Use it when a simple npm install or pip install --upgrade produces a wall of errors, or when a security advisory forces an upgrade that ripples across your entire dependency graph. The prompt forces the model to show its work: it must trace the dependency tree, identify conflict points, propose a valid upgrade order, and flag regressions that require code changes. This is not a prompt for routine patch bumps. It belongs in a workflow where the cost of getting the upgrade wrong is high: production outages, broken builds, or silent runtime failures.

The ideal user has access to the project's lock file, manifest, and a list of packages targeted for upgrade. The model needs concrete version constraints to reason about, not vague intentions. Provide the current dependency graph, the target upgrade, and any known constraints such as pinned sub-dependencies, engine requirements, or monorepo workspace boundaries. The output is a reasoned upgrade plan, not a single command. You should wire this into a CI pre-check, a dependency-management agent, or a developer tool that surfaces risk before the PR is opened. For high-risk production systems, always pair the model's output with a human review step and a dry-run install in a clean environment before merging.

Do not use this prompt for simple patch version bumps where npm update or Dependabot's default behavior suffices. Avoid it when the dependency graph is unavailable or when the upgrade target is a pre-release with unstable transitive dependencies that the model cannot resolve. The prompt is also a poor fit for ecosystems where the model's training data lags behind the latest package releases, as it may hallucinate version numbers or API surfaces. In those cases, fall back to a deterministic resolver with a SAT solver or a manual upgrade path documented by the package maintainers. When the prompt does produce a plan, validate each step against a lock file diff and run the project's full test suite before considering the upgrade complete.

This template is designed to be pasted directly into your orchestration layer, whether that's a Python script, a LangChain node, or a direct API call. It forces the model to reason step-by-step through a dependency graph before proposing an upgrade sequence. The square-bracket placeholders must be replaced with real values from your package manager's output, your lock file, or your CI logs before the prompt is sent to the model. Do not send the placeholder tokens to the model.

textCopy
You are a senior software engineer specializing in dependency management and safe package upgrades.

Your task is to analyze a set of package upgrade requests and produce a safe, ordered upgrade plan. You must reason step-by-step through transitive dependencies, version constraint conflicts, breaking changes, and regression risks before proposing a final sequence.

## Input

**Current Lock File (excerpt):**
[LOCK_FILE_SNIPPET]

**Requested Upgrades:**
[REQUESTED_UPGRADES]

**Known Breaking Changes (from changelogs):**
[BREAKING_CHANGE_NOTES]

**Test Suite Coverage Map:**
[TEST_COVERAGE_MAP]

## Reasoning Steps (perform in order)

1.  **Direct Dependency Analysis:** For each requested upgrade, identify the new version, the current version, and the declared breaking changes.
2.  **Transitive Dependency Expansion:** For each direct dependency, expand its full dependency tree using the lock file. Identify all transitive dependencies that would be added, removed, or bumped.
3.  **Constraint Conflict Detection:** Check all version constraints across the full dependency graph. Flag any conflicts where a parent requires `>=X` but a child requires `<X`. Note the specific packages and version ranges involved.
4.  **Breaking Change Impact Assessment:** Map each breaking change to the specific packages and code paths in the test coverage map that are affected. Estimate regression risk as HIGH, MEDIUM, or LOW based on test coverage.
5.  **Upgrade Ordering:** Propose a sequence of upgrade groups. Each group must be internally compatible and must not break any package in a later group. Justify the ordering.
6.  **Risk Summary:** Provide a final risk assessment for the entire upgrade batch.

## Output Schema

Return ONLY a valid JSON object with this structure:

{
  "analysis": {
    "direct_dependencies": [
      {
        "package": "string",
        "current_version": "string",
        "target_version": "string",
        "breaking_changes_summary": "string"
      }
    ],
    "transitive_impact": [
      {
        "package": "string",
        "action": "ADDED | REMOVED | BUMPED",
        "from_version": "string | null",
        "to_version": "string | null",
        "parent": "string"
      }
    ],
    "constraint_conflicts": [
      {
        "package_a": "string",
        "constraint_a": "string",
        "package_b": "string",
        "constraint_b": "string",
        "conflict_description": "string"
      }
    ]
  },
  "upgrade_plan": [
    {
      "group": 1,
      "packages": ["string"],
      "justification": "string",
      "regression_risk": "HIGH | MEDIUM | LOW",
      "affected_test_paths": ["string"]
    }
  ],
  "overall_risk_assessment": {
    "risk_level": "HIGH | MEDIUM | LOW",
    "summary": "string",
    "recommended_rollback_trigger": "string"
  }
}

## Constraints

- Do not propose an upgrade order that violates version constraints.
- If a conflict cannot be resolved, flag it in `constraint_conflicts` and do not include the conflicting packages in the upgrade plan.
- If regression risk is HIGH and test coverage is LOW, recommend manual review before proceeding.
- Base all reasoning strictly on the provided lock file, changelogs, and test coverage map. Do not invent package relationships.

Adaptation Notes: The [LOCK_FILE_SNIPPET] should include the relevant top-level dependencies and at least one level of their transitive dependencies. The [TEST_COVERAGE_MAP] is critical for the risk assessment step; if you don't have a coverage map, replace that section with a static list of critical code paths and mark the risk as MEDIUM by default. For high-risk production deployments, always route the final upgrade_plan through a human approval step before executing any package manager commands. Validate the JSON output against the schema before processing it in your CI pipeline.

This prompt is designed to be called programmatically, not just used in a chat interface. The implementation harness should treat the model output as a structured reasoning artifact that downstream tooling can parse, validate, and act on. The primary integration points are: a CI pipeline that blocks merges when dependency conflicts are detected, a dependency-management agent that proposes and applies safe upgrade sequences, or a developer CLI tool that surfaces reasoned upgrade plans before manual execution. In all cases, the harness must extract the final upgrade plan from the chain-of-thought reasoning, validate it against the actual package manager's constraint solver, and present results with clear pass/fail signals.

Pipeline Integration Pattern: Wrap the prompt call in a script that accepts a package.json, requirements.txt, Cargo.toml, or equivalent manifest as input. The harness should: (1) Extract current direct and transitive dependencies using the native package manager (npm ls --all, pipdeptree, cargo tree). (2) Identify outdated or conflicting packages using npm outdated, pip list --outdated, or cargo update --dry-run. (3) Assemble the prompt context with the dependency tree, version constraints, and known breaking-change changelogs if available. (4) Call the model with response_format set to a JSON schema that separates the chain-of-thought reasoning from the structured upgrade plan. (5) Parse the output and run the proposed upgrade sequence in a dry-run mode (npm install --dry-run, pip install --dry-run). (6) If the dry-run fails, feed the error back to the model as a correction step with a retry prompt. (7) On success, output the plan as a machine-readable artifact (JSON or YAML) that the CI system can consume. Model Choice: Use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) for the initial resolution. A smaller, faster model can handle the retry loop if the error message is well-structured. Retry Logic: Implement a maximum of 2 retries. If the model cannot produce a valid upgrade plan after 2 correction attempts, the harness should fail explicitly and surface the unresolved conflicts for human triage. Log every attempt, the model's reasoning, and the dry-run error for auditability.

Validation and Safety Checks: Before applying any upgrade, validate that the proposed version sequence satisfies all declared version constraints. Cross-reference the plan against known vulnerability databases (e.g., npm audit, pip-audit, GitHub Advisory Database) to ensure no known-CVE versions are introduced. For high-risk production systems, require a human approval gate: the harness should generate a summary of breaking changes, affected downstream dependents, and test coverage gaps, then pause for manual sign-off before applying changes. Tool Use: If your deployment supports function calling, provide the model with a resolve_dependencies tool that wraps the native package manager's constraint solver. This lets the model test its own hypotheses during the chain-of-thought process rather than guessing at constraint satisfaction. The tool should return a structured result indicating whether the proposed version set is solvable, and if not, which packages conflict. This dramatically reduces post-hoc validation failures.

CLI and Agent Integration: For developer CLI tools, render the chain-of-thought reasoning as a collapsible detail section so developers can inspect the model's logic without being overwhelmed. The primary output should be a concise upgrade plan with clear action items: which packages to upgrade, in what order, with what breaking-change mitigations. For autonomous dependency-management agents (e.g., Renovate or Dependabot-style bots), the harness should run on a schedule, open pull requests with the reasoned upgrade plan in the PR description, and include the full chain-of-thought trace in a collapsible <details> block for reviewer inspection. What to Avoid: Do not apply upgrades automatically without dry-run validation. Do not trust the model's version numbers without verifying them against the package registry. Do not skip the retry loop on dry-run failure—silent failures here lead to broken builds. Do not use this prompt for monorepos with interdependent local packages without first resolving internal dependency graphs separately.