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.
ln-823-pip-upgrader
Type: L3 Worker
Category: 8XX Optimization
Parent: ln-820-dependency-optimization-coordinator
Upgrades Python dependencies with automatic breaking change detection.
Overview
| Aspect | Details |
|---|
| Input | Project path, package manager type |
| Output | Updated requirements.txt/pyproject.toml |
| 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 OR pyproject.toml OR Pipfile | Yes | Block upgrade |
| Virtual environment active | No | Warn user (risk of system pollution) |
| Git clean state | Yes | Block (need clean baseline for revert) |
Workers assume coordinator (ln-820) already verified git state and created backup.
Worktree & Branch Isolation
MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-823 row.
Phase 1: Detect Manager
| Manager | Indicator Files |
|---|
| pip | requirements.txt |
| poetry | pyproject.toml + poetry.lock |
| pipenv | Pipfile + Pipfile.lock |
Phase 2: Security Audit
Commands
| Manager | Command |
|---|
| pip | pip-audit --json |
| poetry | poetry audit (via plugin) |
| pipenv | pipenv check |
Actions
| Severity | Action |
|---|
| Critical | Block upgrade, report |
| High | Warn, continue |
| Moderate/Low | Log only |
Phase 3: Check Outdated
Commands
| Manager | Command |
|---|
| pip | pip list --outdated --format=json |
| poetry | poetry show --outdated |
| pipenv | pipenv update --outdated |
Phase 4: Apply Upgrades
Commands
| 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 Order (Fallback Strategy)
| 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, community solutions |
Context7 Usage
| Step | Tool | Parameters |
|---|
| 1. Find library | mcp__context7__resolve-library-id | libraryName: "pydantic" |
| 2. Query docs | mcp__context7__query-docs | query: "pydantic v1 to v2 migration breaking changes" |
MCP Ref Usage
| Action | Tool | Query Example |
|---|
| Search | mcp__Ref__ref_search_documentation | "python pydantic 2 migration guide" |
| Read | mcp__Ref__ref_read_url | URL from search results |
WebSearch Fallback
Use when Context7/Ref return no results:
"<package> python <version> breaking changes migration""<ImportError message> <package> fix"
Phase 5: Verify Installation
Commands
| Check | Command |
|---|
| Import test | python -c "import <package>" |
| Tests | pytest or python -m pytest |
Phase 6: Report Results
Report Schema
| Field | Description |
|---|
| project | Project path |
| packageManager | pip, poetry, or pipenv |
| duration | Total time |
| upgrades[] | Applied upgrades |
| verification | PASSED or FAILED |
Common Breaking Changes
MANDATORY READ: Load breaking_changes_patterns.md for full patterns.
| Package | Breaking Version | Key Changes |
|---|
| pydantic | 1 → 2 | V1 compatibility layer needed |
| sqlalchemy | 1 → 2 | Query syntax changes |
| fastapi | 0.99 → 0.100+ | Pydantic v2 required |
Configuration
Options:
# Upgrade scope
upgradeType: major # major | minor | patch
# Security
auditLevel: high
minimumReleaseAge: 14
# Python specific
pythonVersion: "3.12"
useVirtualenv: true
# Verification
runTests: true
Error Handling
| Error | Cause | Solution |
|---|
| ImportError | Breaking API change | Search Context7/Ref for migration |
| Dependency conflict | Version mismatch | Try pip-compile or poetry lock |
References
Definition of Done
- Package manager detected (pip/poetry/pipenv) from indicator files
- Security audit completed (pip-audit/poetry audit/pipenv check)
- Outdated packages identified and listed
- Upgrades applied with requirements.txt/pyproject.toml updated
- Breaking changes handled via MCP migration guides
- Import tests and pytest pass after upgrades
- Report returned with upgrades applied and verification status
Version: 1.1.0
Last Updated: 2026-01-10