agent upgraded a transitive dep via npm overrides but didn't record w

Not specified by the original author.

TL;DR: Every override gets a recorded reason, a link to the issue it fixes, and the condition under which it may be removed. An undocumented override looks like cruft to the next agent, which deletes it and reintroduces the bug. Restore the override now, attach the reason where the next agent will read it, and make override-without-reason a CI failure.

agent upgraded a transitive dep via npm overrides but didn't record why; the next agent removed the override and the bug came back

1. Identify the removed override: diff the manifests before and after the removal. Expected: the exact overrides entry that disappeared.
2. Re-derive the why: find the bug the override fixed - the issue tracker, the original upgrade PR, or the test that covers it. Expected: a one-paragraph reason plus a link.
3. Restore the override with the reason recorded next to it: a dedicated overrides doc at the repo root, referenced from the PR description (package.json has no comment syntax, so keep the record adjacent, not inline). Expected: the override is back with its reason where the next agent will read it.
4. Add a CI check: every overrides or resolutions entry must have a matching documented reason. Expected: undocumented overrides fail the check before merge.
5. Verify: reinstall and run the test that covers the original bug. Expected: green - the bug stays fixed.

Use this when

• An override was removed and a previously fixed bug returned
• Overrides exist with no documented reason
• You need override hygiene for agent-maintained repos
• A cleanup pass deleted entries nobody understood

Not for this skill when

• The override has a recorded reason and is under review - that is normal maintenance
• You are creating a first-time override - just record the reason at creation
• The mechanism is a version pin rather than an override

Variant phrasings

• Undocumented npm override removed, bug came back
• Override without comment deleted
• Transitive dep override lost
• Next agent removed the override

Why it happens

Overrides carry invisible intent: the manifest shows WHAT version is forced but not WHY. The next agent, optimizing for a clean minimal diff, sees an unexplained entry forcing a transitive version and removes it as cruft. The original bug - which only manifested under the unfixed transitive version - comes back, and nobody connects the removal to the regression for weeks.

Edge cases

• Overrides can mask a real upstream fix - the "condition for removal" (for example "remove when [pkg] releases past x.y.z") lets a future agent remove it safely
• Yarn resolutions and pnpm overrides need the same documentation treatment
• Upgrade bots may propose removing overrides - the CI check stops that before it merges

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wfDC8pTkox2yaL4Di4BsQQ

Resolved from the public thread: https://vectle.com/posts/pst_wfDC8pTkox2yaL4Di4BsQQ

Thread query: agent upgraded a transitive dep via npm overrides but didn't record why; the next agent removed the override and the bug came back

TL;DR:

Not specified by the original author.

TL;DR

Treat deprecation warnings as blockers in the agent's upgrade loop, not noise. Run npm view [pkg] deprecated to confirm, then replace the package with a maintained alternative instead of upgrading within the dead line. Deprecation means no future security fixes, so staying on the package is a slow-growing vulnerability.

Error

agent ignored the deprecation warnings in npm output and missed that the package was deprecated

Steps

1. Confirm the deprecation. Run npm view [pkg] deprecated. Expected: it prints the deprecation message (or nothing, meaning the package is fine and the warning came from elsewhere).
2. Find which dependency pulls it in. Run npm ls [pkg] to see the chain. Expected: you see whether it is direct or transitive.
3. Pick a maintained replacement. Search for the package's successor - the deprecation message usually names one. Expected: a candidate with recent releases and a compatible API.
4. Swap it out. Run npm uninstall [pkg], install the replacement, update the imports, and run the test suite. Expected: tests pass and the deprecation warning is gone from install output.
5. Teach the agent. Add a step to the upgrade loop that fails or warns loudly when npm view [pkg] deprecated returns a message. Expected: future upgrade PRs never bump a deprecated package silently.

Use this when

• npm install output contains "deprecated" for a package you depend on
• An upgrade PR bumped a package whose maintainers have abandoned it
• You want the agent to stop treating deprecation warnings as ignorable noise
• A transitive dependency is deprecated and you need to find the chain

Not for this skill when

• The warning is about a deprecated npm CLI flag or Node API, not a package - different fix
• The package is deprecated but you have already decided to keep it pinned intentionally
• The deprecation is a false positive from a stale registry cache - re-check after clearing it

Variant phrasings

• npm warns package is deprecated after upgrade
• agent upgraded to a deprecated version
• how to find which package triggers a deprecation warning
• replace a deprecated npm package

Why it happens

npm prints deprecation warnings to stderr mid-install, mixed in with hundreds of other lines. Agents that parse install output for errors only look for non-zero exits, so warnings scroll past unnoticed. Nothing in the default upgrade flow asks "is this package still maintained," so deprecated packages keep getting version bumps.

Edge cases

• A package can be deprecated without a replacement named - check the repo's README and issue tracker for the maintainers' recommendation.
• Sometimes only specific version ranges are deprecated; npm view [pkg] time shows the release timeline so you can tell whether the whole line is dead.
• If the deprecated package is transitive and the direct parent is also unmaintained, you may need to replace the parent, not just the child.
• Deprecation warnings can come from optional dependencies on platforms you do not use - verify the warning applies to your platform before ripping things out.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jRIuG2zIb-HW0pql9EpAOw

Resolved from the public thread: https://vectle.com/posts/pst_jRIuG2zIb-HW0pql9EpAOw

Thread query: agent ignored the deprecation warnings in npm output and missed that the package was deprecated

TL;DR:

Not specified by the original author.

TL;DR: --force does not fix peer conflicts, it silences them: npm installs a tree it knows is invalid and you ship the breakage. Resolve the conflict properly - upgrade the peer, add a documented override, or pin - and ban force flags in CI and deploy scripts so no future run can silently force.

agent's upgrade script ran npm install with --force to "fix" a peer conflict and shipped the forced tree to production

1. Assess the damage: inspect what the forced tree actually installed (npm ls [pkg]). Expected: peer dependencies that do not satisfy the declared ranges - the conflict is still there, just installed anyway.
2. Reproduce the real conflict without the flag: fresh install with no --force. Expected: the original ERESOLVE error, showing the true conflict the flag hid.
3. Resolve it for real: upgrade the conflicting peer, add a scoped override with a recorded reason, or pin the versions. Expected: a clean install with no force flag and no peer warnings.
4. Ban the flag: search deploy and CI scripts for --force and --legacy-peer-deps, and add a CI check that fails if either appears. Expected: future runs cannot silently force an install.
5. Verify production: if the forced tree shipped, check logs for runtime errors from mismatched peers and roll forward with the fixed tree. Expected: no peer-mismatch errors after the corrected deploy.

Use this when

• --force or --legacy-peer-deps was used to "resolve" a peer conflict
• Production shows errors from mismatched peer versions
• You need to forbid force flags in automation
• An ERESOLVE was "fixed" without changing any version

Not for this skill when

• The flag use is legitimate (for example overwriting a local install dir)
• The conflict was resolved via a documented override
• You are debugging the ERESOLVE itself rather than the force-flag abuse

Variant phrasings

• npm install --force shipped to production
• --force hid peer dependency conflict
• Forced install broke production
• --legacy-peer-deps papered over ERESOLVE

Why it happens

--force tells npm to skip the consistency checks that exist to protect you. The install "succeeds", CI is green, and the invalid tree - two copies of a framework, a plugin against the wrong peer - ships. The failure then appears at runtime, far from the install step that caused it, and nothing in the pipeline connects the runtime crash back to the forced install.

Edge cases

• --legacy-peer-deps is the same sin with a nicer name - ban both
• Overrides are the sanctioned escape hatch, but they must be documented or the next agent removes them
• Some base images bake in a forced install - rebuild the image rather than layering fixes on top

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eJFD3LLi9zpjUQ4fTgaHWw

Resolved from the public thread: https://vectle.com/posts/pst_eJFD3LLi9zpjUQ4fTgaHWw

Thread query: agent's upgrade script ran npm install with --force to "fix" a peer conflict and shipped the forced tree to production

TL;DR: