ahgraber/python-workflow-delivery

Python Workflow and Delivery

Overview

Branch-to-PR execution discipline for Python work: validate, scope, and ship with confidence. Apply these defaults before opening or updating a PR.

These are preferred defaults for common cases, not universal rules. When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

When to Use

• Preparing a branch or PR for Python changes.
• CI gate failures on lint, format, or test steps.
• Lockfile or dependency conflicts during uv sync.
• Commits that bundle too many concerns or are hard to review.
• Uncertainty about which validation steps to run before merge.

When NOT to use:

• Pure design or architecture decisions — see python-design-modularity.
• Test strategy or fixture design — see python-testing.
• Runtime operations or deployment — see python-runtime-operations.

Quick Reference

• Use the project-defined Python version first.
• Use uv for environment and dependency workflow.
• Run checks with uv run ....
• Keep scope small, reversible, and reviewable.

Validation Gate

Run as required by project scope:

• uv sync
• uv sync --locked
• uv lock --check
• uv run ruff check .
• uv run ruff format --check .
• uv run pytest

Change-specific checks:

• Dependency/lockfile changes: uv run pytest scripts/test_pypi_security_audit.py -v
• Async lifecycle changes: run pyleak diagnostics on representative async integration tests.

Common Mistakes

• Skipping uv lock --check — merging without verifying the lockfile matches pyproject.toml causes CI failures downstream.
• Bundling unrelated changes in one commit — mixing refactors, features, and dependency bumps makes review slow and reverts dangerous.
• Running ruff check but not ruff format --check — passing lint does not guarantee formatting; both gates matter.
• Forgetting change-specific checks — dependency updates need the security audit; async changes need leak diagnostics. Generic pytest alone is not enough.

Scope Note

• Treat these recommendations as preferred defaults for common cases, not universal rules.
• If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
• When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

Invocation Notice

• Inform the user when this skill is being invoked by name: python-design-modularity.

References

• references/workflow.md
• references/branch-commit-scope.md