Dependency Drift Detection Prompt

This prompt is designed for platform engineers, architects, and technical leads who need to detect and quantify dependency drift in a codebase over time. The job-to-be-done is automated surveillance: comparing the declared dependencies in a project's manifest files (e.g., package.json, go.mod, Cargo.toml) against the actual import or require statements in the source code. The output is a structured drift report that surfaces stale declarations (packages declared but unused) and undeclared usage (packages used but not formally declared), which are primary vectors for supply chain risk, broken builds, and license non-compliance.

You should use this prompt when you have access to both a dependency manifest and a source tree, and you want to integrate the check into a CI/CD pipeline or a periodic scanning harness. The prompt assumes the input is a pre-processed, machine-readable diff or a structured list of declared vs. actual imports, not raw file trees. It is ideal for teams that want to enforce a policy where the manifest is the single source of truth. Do not use this prompt for initial architecture review, for evaluating the quality of a dependency, or for detecting circular dependencies—those are separate, specialized tasks. This prompt is also not a replacement for a Software Composition Analysis (SCA) tool that checks for known vulnerabilities; it focuses strictly on the delta between declaration and usage.

The prompt is most effective when the risk of undeclared dependencies is high, such as in regulated environments, monorepos with shared libraries, or projects with strict license auditing requirements. It requires a human-in-the-loop review step for any detected drift before auto-remediation, as a package might be intentionally used without a manifest entry during local development or testing. Before using this prompt, ensure you have a pre-processing step that extracts and normalizes package identifiers from both the manifest and the source code into a consistent format (e.g., namespace/package@version). The next section provides the exact prompt template you can adapt and embed in your scanning harness.

This prompt template is the core instruction set for a Dependency Drift Detection scan. It is designed to be parameterized with your project's specific package manifest, import graph, and output requirements. The model is instructed to act as a meticulous build engineer, cross-referencing two structured inputs to produce a precise, actionable drift report. The primary goal is to identify 'stale declarations' (packages declared but not used) and 'undeclared usage' (packages used but not declared), which are the two most common forms of dependency rot that lead to broken builds, security vulnerabilities, and difficult onboarding.

textCopy
You are a build system auditor. Your task is to compare a project's declared dependencies against its actual import statements to detect drift.

# INPUTS
[DECLARED_DEPENDENCIES]
[ACTUAL_IMPORTS]

# OUTPUT_SCHEMA
Return a single JSON object with the following structure:
{
  "project": "[PROJECT_NAME]",
  "scan_timestamp": "[SCAN_TIMESTAMP]",
  "drift_report": {
    "stale_declarations": [
      {
        "package": "string",
        "declared_version": "string",
        "last_used_date": "string or null",
        "removal_risk": "LOW | MEDIUM | HIGH",
        "notes": "string"
      }
    ],
    "undeclared_usage": [
      {
        "package": "string",
        "imported_in_file": "string",
        "estimated_version_used": "string or null",
        "integration_risk": "LOW | MEDIUM | HIGH",
        "notes": "string"
      }
    ],
    "version_mismatches": [
      {
        "package": "string",
        "declared_version": "string",
        "locked_version": "string or null",
        "latest_version": "string or null",
        "notes": "string"
      }
    ]
  },
  "summary": {
    "total_stale": "integer",
    "total_undeclared": "integer",
    "total_mismatches": "integer",
    "overall_health": "HEALTHY | WARNING | CRITICAL"
  }
}

# CONSTRAINTS
- Classify a package as 'stale' only if it has zero imports across the entire codebase provided in [ACTUAL_IMPORTS].
- Classify a package as 'undeclared' if it appears in [ACTUAL_IMPORTS] but not in [DECLARED_DEPENDENCIES].
- For `removal_risk`, use 'HIGH' if the package is a core framework, 'MEDIUM' if it's a utility library, and 'LOW' if it's a type definition or development-only tool.
- For `integration_risk`, use 'HIGH' if the undeclared package is a transitive dependency that could be removed by a parent package update, 'MEDIUM' if it's a direct but undeclared dependency, and 'LOW' if it's a standard library or universally available package.
- Do not invent or assume any import that is not present in the provided [ACTUAL_IMPORTS] list.
- If a package is declared but its usage is only in test files, note this in the `notes` field but still flag it as stale for the main application.

To adapt this template, replace the placeholders with data from your build system and code analysis tools. [DECLARED_DEPENDENCIES] should be populated with the parsed contents of your package.json, requirements.txt, Cargo.toml, or equivalent manifest. [ACTUAL_IMPORTS] should be a structured list of all import statements extracted from your codebase, typically generated by a static analysis tool or a simple grep command. The [PROJECT_NAME] and [SCAN_TIMESTAMP] fields should be injected by your automation harness to ensure every report is traceable to a specific scan. The output schema is strict JSON to allow for direct ingestion into a monitoring dashboard or CI/CD pipeline.

The Dependency Drift Detection Prompt is designed to run as a periodic batch job, not a one-off chat interaction. You should wire it into a scheduled pipeline (e.g., a CI/CD cron job, a GitHub Actions workflow, or an internal platform task runner) that executes weekly or per-release. The harness must collect three inputs before each run: the declared dependency manifest (e.g., package.json, requirements.txt, Cargo.toml), the actual import graph extracted from the codebase via a static analysis tool (e.g., depcruise, madge, pydeps), and a set of [DRIFT_RULES] that define what constitutes a violation (e.g., 'undeclared production dependency is a HIGH severity drift', 'stale declaration unused for >90 days is MEDIUM'). The prompt itself should never scrape the codebase; the harness is responsible for producing a clean, structured diff between declared and actual dependencies before the model ever sees it.

Build the harness with a three-stage pipeline: Extract, Detect, and Report. In the Extract stage, run your static analysis tool to produce a machine-readable dependency graph (JSON or CSV) and parse your manifest files into the same format. Compute a mechanical diff that identifies three categories: declared_but_unused, used_but_undeclared, and version_mismatch. This diff is the [DEPENDENCY_DIFF] input to the prompt. In the Detect stage, call the LLM with the prompt template, passing the diff, the [CODEBASE_CONTEXT] (repository name, primary language, build system), and the [DRIFT_RULES]. Configure your model client with temperature=0 and a low top_p value to maximize deterministic output. Set a timeout of 30 seconds and implement a retry strategy: one immediate retry on 5xx or timeout, then a single retry with exponential backoff (2s delay) on malformed JSON output. If the second retry also produces invalid JSON, log the raw response and escalate to a human reviewer rather than silently failing.

The model output must conform to a strict JSON schema. Implement a post-processing validator that checks: every drift item has a non-empty dependency_name, drift_type is one of the allowed enum values (undeclared_usage, stale_declaration, version_drift), severity is one of HIGH, MEDIUM, LOW, and every evidence field contains at least one file path that can be verified against the repository. If validation fails, do not silently accept the output. Route the failure to a dead-letter queue for manual inspection. For high-severity drifts (undeclared production dependencies, stale declarations in security-critical packages), the harness should automatically open a ticket in your issue tracker (e.g., Jira, GitHub Issues) with the drift details and evidence paths pre-populated. For medium and low drifts, append the findings to a running drift log that the team reviews during sprint planning.

Choose your model based on the complexity of your dependency graph. For repositories with fewer than 100 dependencies, a fast model like claude-3-haiku or gpt-4o-mini is sufficient and cost-effective. For monorepos or projects with 200+ dependencies and complex version ranges, use a more capable model like claude-3.5-sonnet or gpt-4o to reduce false positives in drift classification. Always log the model version, prompt version, and input hash alongside each run's output. This audit trail is essential when a team member questions why a dependency was flagged—you can replay the exact run. Store results in a structured format (e.g., a database table or a JSON log file) so you can track drift trends over time. A dashboard showing drift count by severity and by sprint gives engineering leads a leading indicator of dependency hygiene decay before it causes a production incident.

Avoid running this prompt on every commit. Dependency drift detection is a trend analysis tool, not a per-PR gate. Running it too frequently generates noise and desensitizes the team to drift alerts. Instead, schedule it weekly or align it with your release cadence. Also avoid the temptation to auto-fix drifts. The prompt identifies problems; it does not have the context to decide whether an undeclared dependency is intentional (e.g., a peer dependency provided by a parent project) or a stale declaration is kept for documentation purposes. Every drift item should require human triage. The harness's job is to surface the right information, at the right time, with enough evidence that a human can decide in under a minute.