ln-713-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.

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

• breaking_changes_patterns.md
• python_venv_handling.md

---

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