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