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-713-pip-upgrader
Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader
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
See diagram.html for visual 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) |
Workers assume coordinator (ln-710) already verified git state and created backup.
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