Lock File Diff Review Prompt Template

Lock file diffs in pull requests are dense, machine-generated, and nearly impossible to review manually at scale. A single dependency update can pull in dozens of transitive packages, change integrity hashes, or introduce unexpected registries. This prompt template converts a raw lock file diff into a structured, human-readable summary that platform engineers can use to decide whether a change is safe, needs scrutiny, or should be blocked. Use it in CI/CD pipelines, PR review automation, or as a pre-merge checklist assistant. It does not replace security scanning or vulnerability databases; it makes the diff itself legible so human reviewers can spot anomalies that automated tools miss.

The ideal user is a platform engineer, DevSecOps practitioner, or technical lead responsible for dependency hygiene who needs to review lock file changes before they merge. Required context includes the raw lock file diff, the package ecosystem (npm, pip, cargo, etc.), and optionally the PR description or changelog notes. This prompt works best when the diff is focused on a single update or a small batch of related updates. For large-scale dependency migrations spanning hundreds of packages, break the diff into smaller chunks or use this prompt iteratively per package group. The prompt assumes the lock file format is known and parseable; if the diff contains merge conflicts or corrupted entries, pre-process the input before invoking the prompt.

Do not use this prompt as a substitute for automated vulnerability scanners, Software Bill of Materials (SBOM) generators, or cryptographic integrity verification tools. It will not detect malicious packages through behavioral analysis, nor will it assess the exploitability of known CVEs. The prompt's value is in making the diff human-readable and surfacing anomalies—unexpected package additions, suspicious version jumps, registry changes, or removed integrity hashes—that warrant deeper investigation. Always pair this prompt with your existing supply chain security tooling. For high-risk production deployments, require human approval on the summary before merge, and log the prompt output alongside the PR for auditability.

This prompt template is designed to be pasted directly into your AI harness with a lock file diff and a set of configuration variables. It instructs the model to act as a platform engineering reviewer, producing a structured, actionable summary of what changed in a dependency update. The template uses square-bracket placeholders that you must replace with actual data before execution. Do not use this prompt for raw source code diffs or for generating commit messages; it is specifically tuned for the structured output of package manager lock files (e.g., package-lock.json, Cargo.lock, Pipfile.lock).

textCopy
You are a platform engineering reviewer analyzing a lock file diff from a pull request. Your task is to produce a concise, human-readable summary of the changes that is suitable for a code reviewer to quickly understand the impact of a dependency update.

## Input Data
- **Lock File Diff:**
```diff
[LOCK_FILE_DIFF]

• Advisory Database Context (Optional):

jsonCopy
[ADVISORY_DATA]

Required Output Sections

1. Change Summary: A one-sentence summary of the primary intent of this update (e.g., "Bumps 'requests' from 2.28.0 to 2.31.0 to apply a security patch").
2. Direct Dependency Changes: A markdown table listing only the top-level dependencies that changed. Columns: Package Name, Previous Version, New Version, Version Delta Type (Major, Minor, Patch, Pre-release), and a Changelog Link placeholder.
3. Transitive Dependency Changes: A markdown table listing packages added or removed in the dependency graph. Columns: Package Name, Action (Added/Removed), and a brief Justification (e.g., "New transitive dependency of 'requests'").
4. Integrity Verification: A statement confirming whether the integrity or resolved hashes for all changed packages match a known-good source, or a warning if they cannot be verified. If advisory data is provided, flag any packages with known vulnerabilities.
5. Risk Flags: A bulleted list of any unexpected or high-risk signals, such as a major version bump in a stable package, the addition of a new package with network access, or the removal of a security-related package.

Constraints

• [CONSTRAINTS: Do not comment on code style or application logic. Only analyze the provided diff. If the diff is empty, state that no changes were detected. If advisory data is provided, correlate it with the changed packages and cite the advisory ID.]
• [OUTPUT_SCHEMA: The final output must be valid Markdown. Do not wrap the response in a code block.]
• [RISK_LEVEL: Medium. The output is informational for a human reviewer. Do not automatically block a build based on this output.]

To adapt this template, replace the [LOCK_FILE_DIFF] placeholder with the actual unified diff of the lock file. The [ADVISORY_DATA] placeholder is optional but strongly recommended for security-sensitive workflows; it should contain a JSON array of advisory objects with id, affected_package, and severity fields. The [CONSTRAINTS] section can be modified to enforce specific policies, such as requiring explicit approval for major version bumps. Before integrating this into a CI/CD pipeline, ensure the model's output is parsed by a validation script that checks for the presence of the required markdown sections to prevent silent failures where the model returns an unstructured paragraph.

The lock file diff review prompt is designed to run automatically on every pull request that modifies a lock file (package-lock.json, yarn.lock, Cargo.lock, Gemfile.lock, poetry.lock, etc.). The implementation harness should trigger the prompt when the diff includes lock file changes, pass the structured diff and optional advisory context, and route the output to the PR review interface. This prompt is not a replacement for human review of high-risk changes—it is a triage accelerator that surfaces what changed, what was added transitively, and whether integrity hashes match expectations. The harness must treat the model output as advisory and subject it to validation before it appears in a developer's review queue.

Wire the prompt into your CI system by adding a workflow step that runs after the lock file diff is computed. Use git diff against the base branch to extract only the lock file changes, then pass the raw diff as [LOCK_FILE_DIFF]. If you maintain a software bill of materials (SBOM) or advisory database, inject known vulnerability data as [ADVISORY_CONTEXT] so the model can cross-reference added packages against active CVEs. The [REVIEW_DEPTH] parameter controls whether the model performs a fast summary (basic) or a deep transitive analysis (deep). For production use, set a timeout of 30–60 seconds and configure a retry policy: one immediate retry on model unavailability, zero retries on validation failure (fail closed). Log every invocation with the PR number, diff size, model version, and output hash for auditability. If the output fails schema validation—missing required fields, unparseable JSON, or empty findings when the diff is non-trivial—block the review from posting and alert the platform team.

The output must pass through a validation layer before it reaches developers. Validate that added_packages, removed_packages, and updated_packages are arrays with required fields (name, version_delta, integrity_hash_change). Check that transitive_additions is populated when REVIEW_DEPTH is deep. If unexpected_changes is non-empty, flag the PR for mandatory human review regardless of other signals. For high-risk repositories (production services, auth systems, payment handling), configure the harness to require human approval on any diff that introduces new packages or changes more than five transitive dependencies. The model's risk_flags array should be mapped to your existing severity taxonomy so that findings integrate with your team's existing review workflow rather than creating a parallel process. Store the raw model output and the validated output as separate artifacts so you can audit when validation changed or rejected the model's response.

Model choice matters for this workflow. Use a model with strong structured output capabilities and a context window large enough to hold the full lock file diff plus advisory context—lock file diffs can be thousands of lines. Claude 3.5 Sonnet and GPT-4o are both suitable; avoid smaller models that may drop fields or hallucinate package names. If you use an open-weight model, run a calibration suite against known lock file diffs with labeled ground truth before enabling the workflow in production. For teams with strict data residency requirements, run the model locally or in a private deployment and ensure the lock file diff never leaves your environment. The prompt does not require internet access or tool calling, so it can run in air-gapped environments as long as advisory context is provided inline.

Before enabling this prompt in production, build a regression test suite from historical lock file diffs where you know the correct summary. Include diffs with no changes (expect empty findings), diffs with only version bumps (expect populated updated_packages), diffs that introduce new packages with deep transitive trees, and diffs where integrity hashes changed without version changes (expect integrity_hash_change: true and a risk flag). Run these test cases on every prompt or model version change. If the model misses a transitive addition or fails to flag an integrity hash mismatch, block the update. The harness should also track output latency and token usage per invocation so you can detect drift in model behavior or cost before it affects developer experience.