# Runbook Dependency Upgrade > Use when performing runbook dependency upgrade — dependency upgrade workflow covering compatibility check, testing, deployment, and monitoring. Use for library upgrades, framework version bumps, runtime updates, or security patch application. - Skill: `cloudthinker-ai/runbook-dependency-upgrade` (Agent Skill) - Install (CLI): `npx skillmds@latest add cloudthinker-ai/runbook-dependency-upgrade` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudthinker-ai/runbook-dependency-upgrade/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: cloudthinker-ai (https://skillmd.com/u/cloudthinker-ai) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/cloudthinker-ai/runbook-dependency-upgrade --- # Dependency Upgrade Runbook Skill Upgrade **{{ dependency_name }}** from **{{ current_version }}** to **{{ target_version }}**. Affected services: **{{ affected_services }}** ## Workflow ### Phase 1 — Compatibility Assessment ``` COMPATIBILITY ASSESSMENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ UPGRADE DETAILS Dependency: {{ dependency_name }} Current: {{ current_version }} Target: {{ target_version }} Change type: [MAJOR / MINOR / PATCH] Release date: ___ End-of-life for current version: ___ CHANGELOG REVIEW [ ] Read changelog / release notes for all versions between current and target [ ] Identify breaking changes: ___ [ ] Identify deprecated APIs being used: ___ [ ] Identify new features to leverage: ___ [ ] Review security advisories (CVEs fixed): ___ DEPENDENCY TREE IMPACT [ ] Check transitive dependency changes [ ] Identify conflicting version requirements [ ] Verify peer dependency compatibility [ ] Check compatibility with other major dependencies: Dependency: ___ (version: ___) — compatible: YES / NO Dependency: ___ (version: ___) — compatible: YES / NO RISK ASSESSMENT Risk level: [LOW / MEDIUM / HIGH / CRITICAL] Estimated code changes required: ___ Estimated testing effort: ___ ``` ### Phase 2 — Code Changes and Local Testing ``` CODE CHANGES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [ ] Create feature branch for upgrade [ ] Update dependency version in manifest: - package.json / pom.xml / requirements.txt / go.mod / Gemfile [ ] Run dependency resolution (npm install / mvn resolve / pip install) [ ] Fix compilation errors: ___ files changed [ ] Update deprecated API calls: ___ call sites [ ] Update configuration for new version requirements [ ] Update type definitions (if applicable) LOCAL TESTING [ ] Application builds without errors [ ] Unit tests pass: ___ / ___ passing [ ] Integration tests pass: ___ / ___ passing [ ] Manual smoke test of critical paths: [ ] Path: ___ — Result: PASS / FAIL [ ] Path: ___ — Result: PASS / FAIL [ ] Path: ___ — Result: PASS / FAIL [ ] Performance benchmark (no regression): Before: ___ ms avg | After: ___ ms avg ``` ### Phase 3 — Staging Deployment and Testing ``` STAGING DEPLOYMENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [ ] Deploy to staging environment [ ] Verify application starts without errors [ ] Run full test suite in staging: Unit: ___ / ___ passing Integration: ___ / ___ passing E2E: ___ / ___ passing [ ] Run performance / load tests: Throughput: ___ RPS (baseline: ___ RPS) Latency p95: ___ ms (baseline: ___ ms) Error rate: ___% (baseline: ___%) [ ] Verify logging and monitoring still functioning [ ] Test rollback procedure in staging: [ ] Revert to {{ current_version }} [ ] Confirm application works on old version [ ] Re-deploy {{ target_version }} SECURITY SCAN [ ] Run dependency vulnerability scan (Snyk, Dependabot, etc.) [ ] No new HIGH/CRITICAL vulnerabilities introduced [ ] License compliance check passed ``` ### Phase 4 — Production Deployment ``` PRODUCTION DEPLOYMENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PRE-DEPLOYMENT [ ] Code review approved [ ] Staging sign-off obtained [ ] Deployment window confirmed [ ] Rollback plan documented and ready [ ] On-call engineer notified DEPLOYMENT STRATEGY [ ] Canary: deploy to ___% of instances first [ ] Blue-green: deploy to inactive environment [ ] Rolling: update instances in batches of ___ EXECUTION [ ] Deploy to production: ___ [ ] Monitor canary / first batch for ___ minutes [ ] Check error rate: ___% (threshold: ___%) [ ] Check latency: ___ ms (threshold: ___ ms) [ ] Proceed with full rollout: YES / ROLLBACK [ ] Full rollout complete at: ___ ``` ### Phase 5 — Post-Deployment Monitoring ``` POST-DEPLOYMENT MONITORING (24-72h) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HEALTH METRICS (check at T+1h, T+4h, T+24h, T+72h) Metric Pre-upgrade Post-upgrade Status ─────────────── ───────────── ───────────── ───────── Error rate ___% ___% OK / WARN Latency (p95) ___ms ___ms OK / WARN Memory usage ___MB ___MB OK / WARN CPU usage ___% ___% OK / WARN Throughput ___RPS ___RPS OK / WARN [ ] No new error patterns in logs [ ] No increase in exception rates [ ] No memory leaks (memory stable over time) [ ] No performance degradation under load [ ] Downstream services unaffected ``` ### Phase 6 — Rollback and Cleanup ``` ROLLBACK (if issues detected) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Trigger: error rate > ___%, latency regression > ___%, crash loops 1. [ ] Revert deployment to previous version ({{ current_version }}) 2. [ ] Verify application healthy on old version 3. [ ] Investigate failure root cause 4. [ ] Fix and re-attempt upgrade CLEANUP (if upgrade successful) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [ ] Merge upgrade branch to main [ ] Remove any temporary compatibility shims [ ] Update documentation with new version [ ] Close upgrade ticket [ ] Plan removal of deprecated API usage (if deferred) [ ] Schedule next dependency review: ___ ``` ## Counter-Rationalizations | Shortcut | Counter | Why | |----------|---------|-----| | "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate | | "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses | | "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears | | "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate | | "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams | ## Output Format Produce a dependency upgrade report with: 1. **Upgrade summary** (dependency, versions, risk level) 2. **Compatibility assessment** with breaking changes identified 3. **Test results** (unit, integration, e2e, performance) 4. **Deployment log** with canary/rollout progression 5. **Post-deployment metrics** comparison (before vs. after) 6. **Issues and follow-up** actions