A one-line UI fix can arrive with hundreds of lockfile lines. That may be a legitimate dependency change, a stale manifest being reconciled, or a package-manager mismatch. File size alone cannot decide. Pause the agent, preserve the patch, compare the manifest and lockfile, and ask which install command produced the change. The example here is a settings button that an agent chose to implement with a new icon package; the review should decide whether that package is needed before accepting its transitive tree.
Preserve the diff and find the cause
Record the PR head or current branch, changed files, and the agent's install or audit commands. Inspect package.json beside the lockfile and any package-manager declaration, workspace configuration, or other lockfile. In the icon example, a new direct dependency in package.json can explain a larger transitive lockfile diff. A lockfile change with no corresponding manifest edit may reflect a previously stale lockfile, package-manager version or configuration, metadata rewrite, or an unintended command. Do not ask the agent to delete the lockfile merely to make the PR look small; it can hide a reproducibility problem. Also do not accept every generated line without identifying the dependency decision.
- Compare the requested feature with the packages added, removed, or upgraded.
- Ask whether an existing component or dependency already supplied the icon.
- Keep the original diff available while investigating; review the final diff after any cleanup.
Check the repository's actual package manager
Look for the committed lockfile and the packageManager field or documented install command. If the repository uses pnpm, an agent running npm install may introduce package-lock.json or rewrite dependency state unrelated to the task. If it uses npm, npm's documentation says install compares package.json with package-lock.json and can update the lockfile when ranges disagree. npm ci instead requires the two to agree and does not write either file. Use the project's pinned tooling and lockfile conventions; do not mix managers to repair a mysterious diff. Different npm or pnpm versions can legitimately serialize metadata differently, so record the versions before attributing every line to a new package.
| Evidence | Possible interpretation | Decision |
|---|---|---|
| New manifest dependency and matching lock entries | Agent added a package for the feature | Review necessity, source, version, and transitive changes |
| Lockfile edits without manifest change | Stale lockfile, resolver/config change, or accidental rewrite | Reproduce with the documented manager before keeping it |
| Second lockfile from another manager | Agent ran an inconsistent install route | Confirm team convention and remove only after a clean reproducibility check |
| Many unrelated version upgrades | Broad install, audit fix, or range drift | Separate the upgrade decision from the requested feature |
Review the actual dependency delta
GitHub's dependency review can display added, updated, and removed packages in supported repositories, including known vulnerability and license information. Its docs also warn that some manifest or lockfile changes may not appear in that view, so inspect the source diff too. For the icon package, identify the exact direct package, resolved version, its new transitives, runtime versus development placement, and any package install scripts or configuration changes. A green vulnerability scan does not prove the package is necessary or safe; a known-vulnerability warning deserves a decision, and lack of a warning is not an endorsement. If the dependency is unnecessary, ask for a code solution using existing assets, then regenerate the lockfile with the repository's normal tool rather than hand-editing generated entries.
- Check whether the package is imported by the shipped code or only left in the manifest.
- Review license and maintenance fit under the project's policy.
- Do not run an automatic audit fix as a side effect of this feature review without examining its broader changes.
Reproduce from a clean checkout
After a proposed correction, use a disposable clean checkout at the PR head and the documented runtime and package-manager version. Install with the project's frozen or clean-install command, then run the targeted build and feature check. For npm, npm ci is the documented frozen route: it fails if package.json and the lockfile disagree instead of rewriting them. Other package managers have their own equivalent flags and workspace rules; verify the command in this repository. A successful install in the agent's long-lived worktree may rely on its existing node_modules or untracked files. Record the command, version, result, and exact commit so the reviewer knows what was actually reproduced.
- Check that the install leaves tracked files unchanged.
- Run the settings-button interaction and a relevant test after the clean install.
- If the clean install fails, use the first error to distinguish missing lock entries, incompatible versions, and environmental setup.
Close with one explicit PR decision
Keep the lockfile when it accurately records an approved dependency or necessary manifest reconciliation. Remove accidental second-manager output or unrelated upgrades through a reviewed follow-up edit and re-run the clean install. If the required change is broad, split the dependency upgrade from the UI fix where practical, with its own tests and reviewer. In Canopy, inspect the final changed-file list and diff at the same branch and commit used for the app preview; the agent's explanation and a green build are supporting evidence, not substitutes for understanding what will be installed. The PR description should state which package changed, why, the locked version, and the clean-install result.
- Recheck the latest PR head after the agent's final edit.
- Keep the exact dependency decision visible to a future maintainer.
- Let the designated reviewer accept the install and supply-chain implications.
Copyable resources
Unexpected lockfile diff review
Use a disposable checkout for clean-install checks; do not paste private registry tokens or full environment files.
Task / PR / latest head commit: [ ]
Manifest, lockfile, packageManager field, and documented install command: [ ]
Agent command that changed dependencies: [ ]
Direct packages added/removed/updated and why: [ ]
Transitive changes, install scripts, vulnerability/license signals: [ ]
Could existing code or assets satisfy the task? [ ]
Unrelated second lockfile or broad upgrade: [ ]
Clean checkout runtime and manager versions: [ ]
Frozen/clean install command and result: [ ]
Tracked files unchanged after install? [ ]
Feature check and relevant tests at same commit: [ ]
Reviewer decision: keep / regenerate / separate / reject, with owner: [ ]Frequently asked questions
Should I revert a lockfile change if the code change is tiny?
First identify the dependency decision and reproduce the project install. A small source change can require a legitimate lock update; reverting it blindly can make clean installs fail.
Why did package-lock.json appear in a pnpm repository?
A second package manager may have been run. Confirm the repository's documented manager and packageManager field, then remove accidental output only after the expected install and build reproduce.
Does GitHub dependency review show every relevant change?
No. GitHub warns that some manifest or lockfile changes may not appear in dependency review. Inspect the source diff and run the repository's clean install as well.
Does a green npm audit settle the review?
No. It reports known advisory data, not whether the package is needed, how it behaves, or whether the finished feature works. Review the decision and final result.