deps-update

Step 1: Snapshot Current State

Before changing anything:

Fetch upstream and check out a clean base:
```
git fetch upstream
git checkout upstream/main
git checkout -b chore/deps-update
```
If the working tree has uncommitted changes, stop and tell the user to commit or stash first. Dependency updates must land on a clean tree.
Run uv lock --check to confirm the lock file is currently consistent
Run uv run python --version to record the Python version

Step 2: Bump Dependencies

If a specific package was requested, bump only that package:

uv lock --upgrade-package {package}
uv sync --group dev --extra evaluation

Otherwise bump everything:

uv lock --upgrade
uv sync --group dev --extra evaluation

Capture the output of uv lock --upgrade — it lists all version changes and is needed for the commit message and report.

After running uv lock --upgrade, check the output for warnings. If a warning indicates a missing extra or incompatible constraint, investigate whether it affects this project. Note any benign warnings in the final report.

Then regenerate the pinned requirements file:

make requirements.txt

This runs uv export under the hood and produces a requirements.txt with hashes for production packages.

Step 3: Verify — Lint and Type Checks

Run the full verification suite:

make format
make verify

If verification passes cleanly, proceed to Step 4.

If verification fails:

Read the error output carefully
Identify which bumped package caused the breakage (often a renamed/removed API, changed type signatures, or new deprecation-as-error)
Fix the calling code to match the new API — do not pin the package back to the old version unless the new version has a confirmed regression
Re-run make format && make verify
Repeat until clean

Step 4: Verify — Unit Tests

Run the unit test suite:

make test-unit

If tests pass, proceed to Step 5.

If tests fail:

Distinguish between test breakage from API changes (assertions on old behavior, mocks of renamed methods) and genuine regressions (new bugs introduced by a library update)
For API changes — update tests and source code to match the new API
For genuine regressions — check the library's changelog and issue tracker. If confirmed upstream bug, pin that specific package to the last working version in pyproject.toml and re-run uv lock && uv sync
Re-run make test-unit
Repeat until clean

Step 5: Verify — Integration Tests

Run the integration test suite:

make test-integration

Same triage approach as Step 4 if failures occur.

Step 6: Report, Commit, and PR

Check which files changed beyond the dependency files:

git diff --name-only

Always present a summary to the user before committing:

Number of packages bumped, with notable version jumps (major versions, security-relevant packages)
Verification status (lint, unit tests, integration tests)
List of all changed files
Any warnings from Step 2 that were deemed benign
Any source/test files modified to fix API changes (with a brief explanation of each fix)

If only pyproject.toml, uv.lock, and requirements.txt changed — commit and raise a PR automatically without asking:

git add pyproject.toml uv.lock requirements.txt
git commit -m "chore: bump dependencies to latest"

Then follow the raise-pr skill to open the PR.

If source or test files were also modified (API change fixes from Steps 3–5) — wait for user acknowledgment before committing. Then commit all changes and follow the raise-pr skill.

Constraints

Clean tree required — do not start if there are uncommitted changes.
Fix forward, not back — prefer updating code to match new APIs over pinning old versions. Only pin back when there's a confirmed upstream regression.
Do not skip verification — all four gates (lint, types, unit tests, integration tests) must pass before committing.
Do not touch unrelated code — only modify files that break due to the dependency bump. No drive-by refactors.
Report honestly — if a test failure looks unrelated to the bump, say so. Let the user decide whether to investigate separately.
No manual requirements.txt edits — always regenerate via make requirements.txt, never hand-edit.

deps-update

Step 1: Snapshot Current State

Before changing anything:

Fetch upstream and check out a clean base:
```
git fetch upstream
git checkout upstream/main
git checkout -b chore/deps-update
```
If the working tree has uncommitted changes, stop and tell the user to commit or stash first. Dependency updates must land on a clean tree.
Run uv lock --check to confirm the lock file is currently consistent
Run uv run python --version to record the Python version

Step 2: Bump Dependencies

If a specific package was requested, bump only that package:

uv lock --upgrade-package {package}
uv sync --group dev --extra evaluation

Otherwise bump everything:

uv lock --upgrade
uv sync --group dev --extra evaluation

Capture the output of uv lock --upgrade — it lists all version changes and is needed for the commit message and report.

Then regenerate the pinned requirements file:

make requirements.txt

This runs uv export under the hood and produces a requirements.txt with hashes for production packages.

Step 3: Verify — Lint and Type Checks

Run the full verification suite:

make format
make verify

If verification passes cleanly, proceed to Step 4.

If verification fails:

Read the error output carefully
Identify which bumped package caused the breakage (often a renamed/removed API, changed type signatures, or new deprecation-as-error)
Fix the calling code to match the new API — do not pin the package back to the old version unless the new version has a confirmed regression
Re-run make format && make verify
Repeat until clean

Step 4: Verify — Unit Tests

Run the unit test suite:

make test-unit

If tests pass, proceed to Step 5.

If tests fail:

Distinguish between test breakage from API changes (assertions on old behavior, mocks of renamed methods) and genuine regressions (new bugs introduced by a library update)
For API changes — update tests and source code to match the new API
For genuine regressions — check the library's changelog and issue tracker. If confirmed upstream bug, pin that specific package to the last working version in pyproject.toml and re-run uv lock && uv sync
Re-run make test-unit
Repeat until clean

Step 5: Verify — Integration Tests

Run the integration test suite:

make test-integration

Same triage approach as Step 4 if failures occur.

Step 6: Report, Commit, and PR

Check which files changed beyond the dependency files:

git diff --name-only

Always present a summary to the user before committing:

Number of packages bumped, with notable version jumps (major versions, security-relevant packages)
Verification status (lint, unit tests, integration tests)
List of all changed files
Any warnings from Step 2 that were deemed benign
Any source/test files modified to fix API changes (with a brief explanation of each fix)

If only pyproject.toml, uv.lock, and requirements.txt changed — commit and raise a PR automatically without asking:

git add pyproject.toml uv.lock requirements.txt
git commit -m "chore: bump dependencies to latest"

Then follow the raise-pr skill to open the PR.

If source or test files were also modified (API change fixes from Steps 3–5) — wait for user acknowledgment before committing. Then commit all changes and follow the raise-pr skill.

Constraints

Clean tree required — do not start if there are uncommitted changes.
Fix forward, not back — prefer updating code to match new APIs over pinning old versions. Only pin back when there's a confirmed upstream regression.
Do not skip verification — all four gates (lint, types, unit tests, integration tests) must pass before committing.
Do not touch unrelated code — only modify files that break due to the dependency bump. No drive-by refactors.
Report honestly — if a test failure looks unrelated to the bump, say so. Let the user decide whether to investigate separately.
No manual requirements.txt edits — always regenerate via make requirements.txt, never hand-edit.