Dependency Resolution Failure Diagnosis Prompt

This prompt is designed for maintainers, build engineers, and platform teams who need to diagnose a failed pip install, npm install, cargo build, or equivalent package manager operation. The job-to-be-done is not just to see the error, but to produce a structured root cause analysis that explains the constraint conflict, identifies the specific packages and version ranges involved, traces the conflict through the transitive dependency graph, and proposes a concrete resolution path with documented trade-offs. The ideal user is an engineer who already has access to the failing environment's error output, the project's dependency manifest (e.g., package.json, Cargo.toml, pyproject.toml), and the lock file (e.g., package-lock.json, Cargo.lock, poetry.lock). Without these three artifacts, the prompt cannot produce a grounded diagnosis.

Do not use this prompt when the failure is a network timeout, disk-full error, or authentication failure during package download. Those are infrastructure problems, not constraint resolution problems. Also avoid this prompt when the user cannot provide the lock file or the full error output—partial information leads to hallucinated dependency graphs and incorrect conflict explanations. This prompt is not a substitute for running pipdeptree, cargo tree, or npm ls; it reasons over the provided artifacts. If the environment is air-gapped or uses a private registry, the prompt still works as long as the manifest and lock file reflect the actual resolution context. For high-risk production deployments, always require human review of the proposed resolution before applying changes to pinned dependencies.

Before using this prompt, gather the complete error output (not just the last line), the manifest file, and the lock file. If the lock file is missing or stale, note that in the input context—the model will flag lower confidence and may recommend regenerating the lock file first. The output should be treated as an expert diagnostic, not an automated fix. The resolution path will include trade-offs such as upgrading a parent dependency, relaxing a version constraint, or forking a transitive dependency. The next step after receiving the diagnosis is to evaluate those trade-offs against your project's stability and security requirements, then apply the chosen resolution in a branch with full CI validation.

This prompt template is designed to be dropped into your AI coding agent or investigation workflow when a package install, update, or build fails due to dependency conflicts. It expects structured inputs—error logs, manifest files, lock files, and any relevant constraints—so the model can produce a grounded conflict explanation rather than a generic guess. The square-bracket placeholders are your injection points; replace them with actual file contents, tool outputs, or policy statements before sending the prompt to the model.

textCopy
You are a dependency resolution diagnostician. Your task is to analyze a package installation failure, identify the root cause conflict, and propose a resolution path with documented trade-offs.

## INPUT

### Error Output
[ERROR_LOG]

### Manifest Files
[MANIFEST_FILES]

### Lock File
[LOCK_FILE]

### Repository Context
- Recent dependency-related commits: [RECENT_DEPENDENCY_COMMITS]
- Relevant configuration files: [CONFIGURATION_FILES]
- Constraint overrides or resolutions already attempted: [ATTEMPTED_RESOLUTIONS]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "conflict_summary": "One-sentence summary of the root cause conflict.",
  "conflict_graph": [
    {
      "package": "string",
      "required_version": "string",
      "constrained_by": "string (package or manifest rule)",
      "constraint_expression": "string"
    }
  ],
  "resolution_paths": [
    {
      "strategy": "string (e.g., 'upgrade_parent', 'pin_transitive', 'relax_constraint', 'fork_dependency')",
      "steps": ["string"],
      "risk_level": "low | medium | high",
      "breaking_change_risk": "string",
      "rollback_plan": "string"
    }
  ],
  "recommended_path": "string (strategy name)",
  "recommendation_rationale": "string",
  "verification_steps": ["string"]
}

## INSTRUCTIONS
1. Parse the error log to identify the specific packages and version constraints involved in the conflict.
2. Cross-reference the manifest and lock files to build the transitive dependency graph for the conflicting packages.
3. Identify the minimal set of constraints that, if changed, would resolve the conflict.
4. For each resolution path, document the trade-offs: what breaks, what needs testing, and how to roll back.
5. If the error log is incomplete or ambiguous, state what additional information is needed before a diagnosis can be confirmed.
6. Do not recommend a resolution that violates explicitly stated constraints in [CONSTRAINTS].
7. If no safe resolution exists within the constraints, recommend escalation to a human maintainer with a clear explanation of the deadlock.

To adapt this template, start by replacing [ERROR_LOG] with the raw terminal output from your package manager. For [MANIFEST_FILES] and [LOCK_FILE], paste the full contents of package.json/requirements.txt/Cargo.toml and the corresponding lock file. The [CONSTRAINTS] placeholder is critical for high-stakes environments—use it to encode policies like "do not downgrade the framework version" or "must maintain compatibility with Node 18." If you're wiring this into an automated pipeline, consider pre-processing the error log to extract only the conflict-relevant lines to keep the prompt within token budgets. For production use, always pair this prompt with a post-generation validation step that checks the output JSON schema and verifies that the recommended resolution does not violate your stated constraints before any automated fix is applied.

This prompt is designed to be integrated into a CI/CD pipeline, a developer CLI tool, or an internal chatbot. The core workflow is: detect a dependency installation failure, capture the error output and relevant manifest files, assemble the prompt, and return a structured diagnosis. The prompt expects [ERROR_LOG], [MANIFEST_FILES], and [LOCK_FILE] as inputs. You must extract these from the build environment before calling the model. Do not pass raw build logs without trimming irrelevant sections; the model performs best when given the specific error block, the package manifest declaring direct dependencies, and the lock file representing the resolved graph.

Implement a validation layer around the model's output. The expected [OUTPUT_SCHEMA] is a JSON object with root_cause, conflict_graph, resolution_paths, and trade_off_summary fields. After receiving the response, validate that conflict_graph contains actual package names and version constraints found in the input files. A common failure mode is the model hallucinating a package name that doesn't exist in the manifest. Implement a post-processing check that cross-references every package mentioned in the diagnosis against the input [MANIFEST_FILES] and [LOCK_FILE]. If a package is not found, flag the output for human review or trigger a retry with a stricter constraint to only reference packages present in the provided files.

For high-risk production environments, route all automated fix suggestions through a human approval step. The resolution_paths array will contain specific version pin changes or dependency overrides. Before applying these, display the proposed diff to the developer and require explicit confirmation. Log the full prompt, model response, and final decision for auditability. This is critical because an incorrect dependency resolution can introduce subtle runtime bugs or security vulnerabilities that pass compilation checks. For model choice, prefer a model with strong reasoning capabilities and a large context window, as lock files can be thousands of lines long. If the lock file exceeds the context window, implement a pre-processing step that extracts only the subgraph relevant to the conflicting packages using a deterministic tree parser before passing it to the model.