Monorepo Dependency Health Check Prompt

This prompt is designed for monorepo maintainers and platform engineers who need to audit cross-package dependency consistency at scale before it causes build failures or runtime errors. The primary job-to-be-done is producing a structured health report that surfaces version misalignments, workspace protocol violations, phantom dependencies, and build ordering constraints across dozens or hundreds of packages. Use it when you suspect dependency drift after a series of merged PRs, before cutting a major release, or as a recurring CI gate that runs nightly against the main branch. The prompt assumes you can provide the full content of every package.json, the workspace configuration file (e.g., pnpm-workspace.yaml, nx.json, or turbo.json), and at least one lockfile that represents the resolved dependency graph. Without these inputs, the model cannot verify whether declared versions match resolved versions or whether packages are using dependencies they never declared.

Do not use this prompt when you need a full build system audit, runtime behavior analysis, or security vulnerability scan. It will not execute npm ls, pnpm why, or any other CLI command; it reasons over the static manifest and lockfile content you provide. It also cannot detect issues that only manifest at runtime, such as dynamic require() calls, conditional imports, or peer dependency mismatches that the package manager silently tolerates. If you need to verify that every dependency resolution is reproducible across environments, pair this prompt with the Build Reproducibility Audit Prompt from the same content group. If you need to assess the risk of merging a specific dependency update PR, use the Dependency Update Risk Assessment Prompt instead. This prompt is a structural health check, not a change approval gate.

Before running this prompt in CI, establish a baseline by running it against a known-good commit and saving the output as a golden reference. Subsequent runs should be diffed against that baseline to catch regressions. The prompt's output includes a prioritized fix list, but every finding must be verified against the actual file declarations before applying changes. A phantom dependency warning, for example, might be intentional if the package relies on a hoisted dependency in a specific workspace layout. Treat the output as an investigation roadmap, not an automated fix script. For high-risk monorepos with compliance requirements, always route findings through human review before merging remediation PRs.

This template produces a structured dependency health report for a monorepo. It is designed to be pasted into an AI coding agent that has access to the repository's file system, allowing it to read package.json files, lockfiles, and build configurations directly. Replace each square-bracket placeholder with the specific paths, package names, and constraints relevant to your workspace before execution. The prompt instructs the model to cross-reference declared dependencies against actual usage, detect workspace protocol violations, and surface phantom dependencies—all findings must be grounded in file evidence.

textCopy
You are a monorepo dependency auditor. Your task is to analyze the dependency health of the monorepo at [REPO_ROOT_PATH] and produce a structured health report.

## Input Context
- Workspace root: [REPO_ROOT_PATH]
- Package manager: [PACKAGE_MANAGER, e.g., pnpm, yarn, npm]
- Workspace configuration file: [WORKSPACE_CONFIG_PATH, e.g., pnpm-workspace.yaml]
- Packages to audit: [PACKAGE_SCOPE, e.g., "all packages" or "packages/*", "apps/*"]
- Lockfile path: [LOCKFILE_PATH, e.g., pnpm-lock.yaml]
- Build tool configurations: [BUILD_CONFIG_PATHS, e.g., "tsconfig.json files in each package"]
- Additional constraints: [CONSTRAINTS, e.g., "ignore devDependencies for audit scope" or "focus on production dependencies only"]

## Audit Steps
1. Discover all packages defined in [WORKSPACE_CONFIG_PATH] matching [PACKAGE_SCOPE].
2. For each package, read its `package.json` and extract `dependencies`, `devDependencies`, `peerDependencies`, and `workspace` references.
3. Cross-reference declared dependencies against the lockfile at [LOCKFILE_PATH] to detect version mismatches and phantom dependencies.
4. Check that all `workspace:*` or `workspace:^` protocol references point to existing packages within the monorepo.
5. For each dependency, verify that the imported package is actually declared in `package.json` (detect phantom dependencies where code imports a package not listed).
6. Analyze the dependency graph to identify circular dependencies between workspace packages.
7. Check for version alignment: identify cases where different packages depend on conflicting versions of the same external dependency.
8. Review build ordering constraints: identify packages that depend on build artifacts from other workspace packages and verify build order is satisfiable.
9. For each finding, record the exact file path and line reference that supports the finding.

## Output Schema
Produce a JSON report with this exact structure:
{
  "summary": {
    "total_packages": number,
    "total_dependencies": number,
    "findings_count": number,
    "critical_count": number,
    "high_count": number,
    "medium_count": number,
    "low_count": number
  },
  "findings": [
    {
      "id": "DH-001",
      "severity": "critical|high|medium|low",
      "category": "version_mismatch|phantom_dependency|workspace_protocol_violation|circular_dependency|version_conflict|build_order_issue|missing_dependency",
      "package": "affected-package-name",
      "description": "Clear description of the finding",
      "evidence": {
        "file": "path/to/file",
        "line_or_section": "specific reference",
        "expected": "what should be present",
        "actual": "what was found"
      },
      "impact": "Description of what breaks or risks this creates",
      "fix_suggestion": "Concrete remediation step"
    }
  ],
  "dependency_graph_issues": {
    "circular_dependencies": [
      {
        "cycle": ["package-a", "package-b", "package-a"],
        "entry_points": ["file-path"],
        "severity": "high|medium|low"
      }
    ],
    "build_order_conflicts": [
      {
        "package": "package-name",
        "depends_on_build_of": ["other-package"],
        "resolution": "suggested build order or refactor"
      }
    ]
  },
  "version_alignment": {
    "conflicts": [
      {
        "dependency_name": "external-pkg",
        "versions_found": {
          "package-a": "1.2.0",
          "package-b": "2.0.0"
        },
        "recommended_version": "2.0.0",
        "migration_effort": "low|medium|high"
      }
    ]
  },
  "prioritized_fix_list": [
    {
      "rank": 1,
      "finding_id": "DH-001",
      "action": "Concrete action to take",
      "effort": "low|medium|high",
      "risk_of_regression": "low|medium|high"
    }
  ]
}

## Constraints
- Every finding MUST include an `evidence` block with the exact file path and reference.
- Do not report a finding unless you can cite the specific file and line that proves it.
- If a package uses a dependency but does not declare it, classify as `phantom_dependency`.
- If a `workspace:*` reference points to a non-existent package, classify as `workspace_protocol_violation`.
- Version conflicts must compare semver ranges against the resolved lockfile version, not just declared ranges.
- If no issues are found in a category, return an empty array for that section.
- Do not suggest fixes that would break the build or change dependency semantics without noting the risk.

## Risk Level
[RISK_LEVEL, e.g., "This is a production monorepo. Findings marked critical or high require human review before any automated fix is applied. Do not apply fixes automatically."]

After pasting this template, verify that the AI coding agent has read access to all package directories and the lockfile. For large monorepos, consider running the audit in stages—first on a subset of packages defined in [PACKAGE_SCOPE] to validate output quality before scaling to the full repository. If the agent produces findings without file evidence, tighten the constraints section or add a post-processing validation step that strips any finding missing an evidence.file field. For production use, always route critical and high-severity findings through human review before applying automated fixes.

This prompt is designed to run as a scheduled or trigger-based job inside a CI/CD pipeline, a monorepo management CLI, or an internal developer portal. The primary integration point is a script or service that collects the required inputs—workspace package.json files, lockfiles, and workspace configuration—assembles them into the [WORKSPACE_MANIFESTS] and [LOCKFILE_DATA] placeholders, and submits the prompt to a capable model (GPT-4o, Claude 3.5 Sonnet, or equivalent). The output is a structured JSON health report that downstream systems can parse, store, and act on.

Input Assembly: Before calling the model, build a deterministic input payload. Walk the monorepo root and each workspace package to extract package.json contents, pnpm-workspace.yaml or equivalent workspace config, and the resolved lockfile (pnpm-lock.yaml, yarn.lock, package-lock.json). Deduplicate and normalize the data into a single JSON object with keys workspaces (map of package path to parsed package.json) and lockfile (parsed lockfile entries). This normalization step prevents the model from hallucinating package names or versions that don't exist in the actual repository. Inject this object into the [WORKSPACE_MANIFESTS] and [LOCKFILE_DATA] placeholders. For large monorepos, consider filtering to only packages that have changed since the last health check, using git diff to scope the input and reduce token cost.

Validation Layer: The model output must pass a strict post-processing validation step before any finding is surfaced to users or acted upon. Parse the JSON output and, for every finding in the findings array, run a verification function that checks the claimed issue against the actual input data. For example, a version misalignment finding must be confirmed by comparing the declared versions in the relevant package.json files. A phantom dependency finding must be verified by checking that the claimed imported package is not declared in the importing workspace's dependencies or peerDependencies. Any finding that fails verification should be discarded and logged as a model hallucination. This validation layer is non-negotiable—without it, the prompt will occasionally produce plausible-sounding but incorrect findings, especially in edge cases involving aliased packages or conditional dependencies.

Retry and Fallback Strategy: If the model returns malformed JSON that cannot be parsed, retry once with a simplified prompt that includes the raw output and a repair instruction: 'The previous output was not valid JSON. Return ONLY the corrected JSON object with the exact schema specified.' If the retry also fails, log the failure, alert the on-call channel, and fall back to a deterministic static analysis tool (such as syncpack for version alignment or dpdm for phantom dependency detection) to produce a partial report. Never silently swallow a parse failure—missing health data is better than incorrect health data.

Human Review Gate: For critical severity findings, especially those involving breaking version mismatches in production-deployed packages or phantom dependencies in security-sensitive paths, route the finding to a human reviewer before any automated fix is applied. The review interface should display the finding, the verification result from the validation layer, and a link to the relevant source files. Only after human approval should an automated remediation PR be created. For low and medium severity findings, automated fix PRs are acceptable if the validation layer confirms the finding and the fix is limited to version bumps or dependency declaration additions.

Logging and Observability: Log every prompt execution with a unique run ID, the input hash (to detect duplicate runs), the model used, token counts, validation pass/fail counts per finding, and any retry events. Store the raw model output and the validated output separately so that prompt drift can be detected over time. If the rate of validation failures (hallucinated findings) exceeds 10% across recent runs, trigger an alert to review the prompt template and input assembly logic. This observability loop is essential because monorepo structures evolve, and prompt performance can degrade as package counts grow or workspace configurations become more complex.