ln-823-pip-upgrader

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-823-pip-upgrader

Type: L3 Worker Category: 8XX Optimization

Upgrades Python dependencies with automatic breaking change detection.

---

Overview

Aspect	Details
Input	Project path plus package manager type
Output	Updated dependency manifests and a machine-readable dependency upgrade summary
Supports	pip, poetry, pipenv

---

Workflow

Phases: Pre-flight -> Detect Manager -> Security Audit -> Check Outdated -> Apply Upgrades -> Verify Installation -> Report

---

Phase 0: Pre-flight Checks

Check	Required	Action if Missing
requirements.txt, pyproject.toml, or Pipfile	Yes	Block upgrade
Python package manager available	Yes	Block upgrade
Virtual environment active	No	Warn user if managed environment is unclear
Workspace baseline safe	Yes	In managed runs coordinator already prepared it; in standalone runs protect rollback locally

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-820. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

---

Phase 1: Detect Manager

Manager	Indicator Files
pip	requirements.txt
poetry	pyproject.toml + poetry.lock
pipenv	Pipfile + Pipfile.lock

---

Phase 2: Security Audit

Manager	Command
pip	pip-audit --json
poetry	poetry audit
pipenv	pipenv check

Actions:

Severity	Action
Critical	Block and report
High	Warn and continue
Moderate/Low	Log only

---

Phase 3: Check Outdated

Manager	Command
pip	pip list --outdated --format=json
poetry	poetry show --outdated
pipenv	pipenv update --outdated

---

Phase 4: Apply Upgrades

Manager	Command
pip	pip install --upgrade <package>
pip (freeze)	pip freeze > requirements.txt
poetry	poetry update
pipenv	pipenv update

---

MCP Tools for Migration Search

Priority	Tool	When to Use
1	mcp__context7__query-docs	First choice for library docs
2	mcp__Ref__ref_search_documentation	Official docs and PyPI
3	WebSearch	Latest info and community fixes

Use MCP tools whenever a package upgrade crosses a major version or introduces import errors.

---

Phase 5: Verify Installation

Check	Command
Import smoke test	python -c "import <package>"
Tests	pytest or python -m pytest

Common breaking examples:

MANDATORY READ: Load breaking_changes_patterns.md for shared patterns.

Package	Breaking Version	Key Changes
pydantic	1 -> 2	Compatibility layer required
sqlalchemy	1 -> 2	Query API changes
fastapi	0.99 -> 0.100+	Pydantic v2 alignment

---

Phase 6: Report Results

Field	Description
project	Project path
packageManager	pip, poetry, or pipenv
duration	Total time
upgrades[]	Applied upgrades
verification	Import/test verdict
warnings[]	Non-blocking issues
artifact_path	Durable worker report path, if written

---

Configuration

Options:
  upgradeType: major          # major | minor | patch
  auditLevel: high
  minimumReleaseAge: 14
  pythonVersion: "3.12"
  useVirtualenv: true
  runTests: true

---

Error Handling

Error	Cause	Solution
ImportError	Breaking API change	Search current migration docs
Dependency conflict	Version mismatch	Regenerate lock file or rollback offending package

---

References

• breaking_changes_patterns.md
• python_venv_handling.md

---

Runtime Summary Artifact

MANDATORY READ: Load shared/references/coordinator_summary_contract.md

Emit a dependency-worker summary envelope.

Managed mode:

• ln-820 passes deterministic runId and exact summaryArtifactPath
• write the summary to the provided summaryArtifactPath

Standalone mode:

• omit runId and summaryArtifactPath
• write .hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-823--{identifier}.json

Monitor (2.1.98+): For install/audit/test commands expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

• [ ] Package manager detected from project indicators
• [ ] Security audit completed for the selected Python manager
• [ ] Outdated packages identified
• [ ] Breaking changes checked via patterns plus current docs
• [ ] Upgrades applied with manifest and lock updates persisted
• [ ] Import smoke test and required tests succeed
• [ ] dependency-worker summary artifact written to the managed or standalone path

---

Version: 1.1.0 Last Updated: 2026-01-10