Dependency Bloat and Unused Package Detection Prompt

Platform engineering teams accumulate unused, duplicated, and unnecessarily pinned dependencies over time. This prompt analyzes import statements against manifest declarations to produce a removal candidate list with justification and risk notes. Use it during dependency audit sprints, before major refactors, or as a scheduled CI hygiene check. The prompt assumes you can provide the package manifest file content and a grep or static analysis output of all import statements. It does not execute code or resolve dynamic imports, so runtime-only dependencies require separate verification.

The ideal user is a platform engineer, tech lead, or DevOps practitioner who can supply two structured inputs: the full content of a package manifest (such as package.json, requirements.txt, Cargo.toml, or go.mod) and a deduplicated list of import statements extracted from the codebase via grep, rg, or a static analysis tool. The prompt works best when imports are normalized to the package names used in the manifest. If your codebase uses path aliases, monorepo internal packages, or conditional imports behind feature flags, preprocess those into canonical package names before passing them to the prompt. The output is a structured removal candidate list, not an automated deletion script—every candidate still requires human review and a passing test suite before removal.

Do not use this prompt for runtime-only dependencies that are never imported statically, such as database drivers loaded via connection strings, plugin systems that discover packages at runtime, or packages consumed only through CLI entry points. It also cannot detect packages that are imported exclusively in test files unless those imports are included in the input. For high-risk production services, pair the prompt's output with a dry-run removal and a full CI pipeline run before merging any dependency changes. The prompt is a triage accelerator, not a replacement for build verification.

The following prompt is designed to be pasted directly into your AI harness. It instructs the model to act as a platform engineering auditor, comparing a provided package manifest against the codebase's import statements. The goal is to produce a structured, actionable list of packages that are unused, duplicated, or unnecessarily pinned, along with a risk-justified removal recommendation.

textCopy
You are a senior platform engineer auditing a project for dependency bloat. Your task is to analyze the provided [PACKAGE_MANIFEST] and [IMPORT_DATA] to identify packages that are declared but not used, are duplicated, or are pinned to an unnecessarily strict version.

## Inputs
- **Package Manifest:** [PACKAGE_MANIFEST]
- **Import Data:** [IMPORT_DATA]
- **Project Context:** [PROJECT_CONTEXT]

## Instructions
1.  **Cross-reference:** Compare every dependency declared in the manifest against the import statements found in the import data.
2.  **Categorize:** Classify each finding into one of the following categories:
    - `UNUSED`: Declared in the manifest but never imported.
    - `DUPLICATE`: The same package is declared multiple times or a sub-package is declared alongside its parent.
    - `OVERLY_PINNED`: The version is pinned to an exact patch when a looser range would be safe based on the project's usage.
    - `DEV_IN_PROD`: A package typically used for development (testing, linting, building) is declared as a production dependency.
3.  **Justify:** For each finding, provide a concise justification. For `UNUSED` packages, note if the package could be a peer dependency or is used in a build script not captured by the import scan.
4.  **Assess Risk:** Assign a removal risk level (`LOW`, `MEDIUM`, `HIGH`) based on the potential for breaking the build, runtime, or development workflow.

## Output Schema
Return a single JSON object with the following structure:
{
  "analysis_summary": {
    "total_dependencies": <number>,
    "unused_count": <number>,
    "duplicate_count": <number>,
    "overly_pinned_count": <number>,
    "dev_in_prod_count": <number>
  },
  "findings": [
    {
      "package_name": "<string>",
      "category": "UNUSED | DUPLICATE | OVERLY_PINNED | DEV_IN_PROD",
      "current_version": "<string>",
      "recommended_action": "<string>",
      "risk_level": "LOW | MEDIUM | HIGH",
      "justification": "<string>"
    }
  ]
}

## Constraints
- Do not flag packages that are used via dynamic imports or reflection unless you have clear evidence from the project context.
- If a package is a well-known peer dependency of another used package, note this in the justification and lower the risk level.
- If the import data is incomplete or ambiguous, state your assumptions clearly in the justification.
- Only return the JSON object. Do not include any other text.

To adapt this template, replace the placeholders with your actual data. [PACKAGE_MANIFEST] should contain the full content of your package.json, requirements.txt, Cargo.toml, or equivalent. [IMPORT_DATA] should be a pre-processed list of all import statements, which you can generate with a tool like grep or a static analysis script. [PROJECT_CONTEXT] is optional but highly recommended; it can include details like the build system used, known dynamic imports, or a list of scripts in package.json that might use otherwise unimported packages. For high-risk production systems, always have a senior engineer review the output before removing any packages.

This prompt is designed to run inside an automated workflow, not as a one-off chat interaction. The most common integration points are a CI pipeline triggered on manifest file changes (e.g., package.json, requirements.txt, Cargo.toml), a scheduled weekly audit job that scans the full repository, or a pull request bot that comments with removal candidates when a dependency is added. The harness must supply the prompt with a structured input containing the dependency manifest content, a list of all import statements extracted from the codebase, and any project-level constraints such as pinned packages that should be excluded from analysis. Without accurate import extraction, the prompt will produce false positives—flagging packages that are actually used but were missed by a naive grep.

Input assembly is the critical pre-processing step. Use a deterministic script to extract imports before calling the model: grep -rE '^(import|from|require|use) ' --include='*.py' --include='*.js' --include='*.ts' --include='*.rs' src/ or a language-specific AST parser for higher accuracy. Combine this with the raw manifest file content and any lock file data. The prompt's [MANIFEST_CONTENT] placeholder expects the full manifest text, [IMPORT_LIST] expects a deduplicated list of imported packages, and [PROJECT_CONSTRAINTS] can include known false positives to suppress (e.g., type stubs, test-only dependencies, build tools that are imported indirectly). Package the assembled input as a JSON object matching the prompt's expected schema before sending it to the model.

Model choice and validation matter for reliability. Use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and request JSON output with a defined schema. Validate the response before acting on it: check that every removal candidate includes a non-empty package_name, justification, and risk_level field. Reject responses where the removal_candidates array is empty but the manifest contains packages not in the import list—this indicates the model missed something. Implement a retry loop with exponential backoff (max 3 attempts) for malformed JSON or schema validation failures. Log every response and validation result for auditability.

Human review gates are essential because removing a dependency can break runtime behavior that static import analysis misses—dynamic imports, plugin systems, configuration-driven loading, or packages required by transitive dependencies that your code doesn't import directly. Configure the harness to open a ticket or PR comment with the removal candidate list rather than automatically deleting packages. Require approval from a platform engineer or tech lead before any package is removed. For high-risk packages (those flagged with risk_level: high), add an additional review step that requires a second approver. The harness should also check whether any removal candidate is a direct dependency of another listed package by consulting the lock file—if so, suppress it from the removal list and log the reason.

Scheduled audit mode requires additional state tracking. Store the previous run's removal candidates and compare them to the current run. Packages that appear as removal candidates across multiple consecutive runs but remain in the manifest may indicate that the team has consciously chosen to keep them—suppress these from future reports or add them to a persistent allowlist. Packages that newly appear as removal candidates should be highlighted as high-priority findings. Integrate the output with your team's notification system (Slack, email, ticketing system) with a summary message: 'Found 3 unused packages (2 low risk, 1 medium risk). Review required.' Avoid alert fatigue by batching low-risk findings into a weekly digest rather than triggering per-run notifications.