Review Dep Upgrade
Developmentreview-dep-upgradeReview Dep Upgrade is an Agent Skill for development published in the react-cosmos/react-cosmos repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Review npm dependency upgrade diffs. Use when comparing upgraded direct dependency versions between refs or package.json changes, fetching npm release dates, sorting by release gap, and summarizing upstream changes plus repo-specific impact.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/react-cosmos/react-cosmos/blob/HEAD/.agents/skills/review-dep-upgrade/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/review-dep-upgrade, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Review Dependency Upgrades
Workflow
-
Identify the comparison range.
- If the user gives refs, use them.
- If not, inspect
git status --shortandgit diff -- package.json '**/package.json'. - For clean worktrees, ask for the base/head refs unless the conversation already provides enough version pairs.
-
Collect direct dependency upgrades.
- Run the helper script (see Helper Script below); it emits JSON sorted by largest release gap.
- The script covers
dependencies,devDependencies,peerDependencies, andoptionalDependencies, skips workspace-internal packages, and dedupes by name/version pair. - Do not include transitive-only
package-lock.jsonchurn unless the user explicitly asks for it. - Mention added or removed direct dependencies separately only when they explain a repo-impact change.
-
Sanity-check the dates.
- If any entry has
"lookupError": true, thenpm viewcall failed for that package (the script also exits non-zero and prints the failure to stderr). Treat this as a tooling problem: request escalation for npm registry access and re-run before presenting the report — do not ship a report withlookupErrorentries. - If a date is
nullwithoutlookupError, that specific version is missing from npm'stimedata — it may have been unpublished or renamed. Call it out in the report. - Keep negative or same-day release gaps in the report, but call them out briefly.
- If any entry has
-
Add analysis.
Notable changes: only upstream changes likely to matter for this repo or the upgrade risk. Prefer official changelogs, migration guides, release notes, or docs. Avoid irrelevant metadata trivia.Repo impact: concrete local files, config changes, test fixes, build/lint failures, orNone observed.- Mark uncertainty explicitly instead of overstating causes.
-
Verify claims.
- Run relevant repo commands when practical, especially tests/build/lint/type-check if discussing required changes.
- Use verification results to inform
Repo impact.
Output
Produce a Markdown section for each dependency, sorted by largest positive release gap first:
### `dependency` — `previous` (YYYY-MM-DD) → `current` (YYYY-MM-DD)
- **Release gap:** 3y 5mo
- **Notable changes:** TODO
- **Repo impact:** TODO
Guidelines:
- Use backticks around package names and versions.
- Use
YYYY-MM-DDfor release dates (slice the script's ISO timestamps). - Use the script's
releaseGapstring verbatim (compact forms like3y 5mo,54d 1h). - If a date is
null, omit the parens for that version. - Fill in
Notable changesandRepo impactfor every entry before presenting the report. Notable changesandRepo impactmay be multiple sentences when needed for important context.- Use
None observed.for repo impact when there is nothing concrete. - End with a
### Sourcessection when upstream summaries depend on browsed pages.
Helper Script
Run from the repo root:
node .agents/skills/review-dep-upgrade/scripts/collect-dep-upgrades.mjs --base HEAD~1 --head HEAD
Defaults: --base HEAD~1, --head worktree. Options:
--base <ref>: git ref for previous versions.--head <ref>: git ref for current versions. Useworktreefor current files on disk.
Emits a JSON array of direct dependency upgrades, sorted by largest release gap, with workspace-internal packages filtered out. Example entry:
{
"dependency": "ts-loader",
"previousVersion": "9.5.4",
"previousDate": "2025-08-24T08:06:29.241Z",
"currentVersion": "9.5.7",
"currentDate": "2026-04-02T07:49:53.845Z",
"releaseGap": "7mo 10d",
"releaseGapMs": 19093404604
}
If npm view fails for a package, its entries gain "lookupError": true, the failure is logged to stderr, and the script exits non-zero. Render the Markdown report (see Output) from this data and fill in Notable changes and Repo impact.