agent upgraded a transitive dep via npm overrides but didn't record why; the next agent removed the override and the...
Fixes undocumented npm overrides: an agent forced a transitive version with no recorded reason, the next agent removed it as cruft, and the original bug came back. Use when an override was deleted and a fixed bug returned. Key trigger: an overrides entry with no documented reason.
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- Identify the removed override: diff the manifests before and after the removal. Expected: the exact overrides entry that disappeared.
- 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.
- 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.
- Add a CI check: every overrides or resolutions entry must have a matching documented reason. Expected: undocumented overrides fail the check before merge.
- 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