b08x/python-dev

Use when diagnosing a Python codebase's problems with Kaizen methods (Gemba Walk, Value Stream, Muda, Root-Cause, Five Whys) or surveying technical debt (code, architecture, technology, testing, docs) with measured units. Maps each method to a Python failure mode and to a handoff key that the cleaner or verifier can act on.

Use for data pipelines and databases in Python: polars lazy frames for CSV and NDJSON, ijson for streaming JSON, msgspec or orjson for fast serialization, SQLAlchemy 2.0 with async sessions and a unit of work, psycopg 3 COPY for bulk loads, redis-om for Redis models, and pgvector for embeddings. Loaded by the implementer when the brief names db-engineer, polars, SQLAlchemy, Postgres, Redis, ETL, or a repository layer.

Use when building LLM-backed components in Python: typed agents with pydantic-ai, provider-neutral calls with litellm, structured output with instructor, DSPy programs and optimizers (GEPA or MIPROv2), MCP servers and clients with FastMCP, and embedding generation (storage and search belong to db-engineer). Loaded by the implementer when the brief names genai, dspy, pydantic-ai, litellm, instructor, or FastMCP.

Use for classical NLP in Python: tokenization, segmentation, POS tagging, and dependency parsing with spaCy; WordNet lookups with the wn package (Open English WordNet); lexical ranking with scikit-learn TF-IDF and bm25s. Loaded by the implementer when the brief names nlp, spaCy, WordNet, BM25, TF-IDF, or POS tagging. Not for LLM work.

Deterministic Python development workflow for Antigravity. Survey and plan, dispatch to the five phase subagents via invoke_subagent, reconcile, then gate and synthesize. Use for any Python task that spans more than one concern.

Run one phase's quality gate and the scope check on the working tree, without dispatching a subagent. Use to check a phase by hand, for example after a scaffold or before a commit.

Use when applying a named refactoring to Python code. Matches a code issue to a known transformation (nested conditionals to guard clauses or match, bare except to narrow exceptions, threads to asyncio, legacy TypeVar to PEP 695, mutable default arguments, dict soup to frozen dataclasses or pydantic models) and applies it as a surgical change. Includes the strangler facade for oversized modules.

Internal phase skill, loaded by the cleaner subagent; do not trigger directly. Use as the Cleaner phase of a Python build: diagnoses first, then refactors until the CRAP score, cyclomatic complexity, and mypy --strict meet their thresholds. Also covers bug diagnosis, named refactorings, and measured performance work. Runs no mutation testing or security scanning.

Internal phase skill, loaded by the hardener subagent; do not trigger directly. Use as the Hardener phase of a Python build: runs mutation testing with mutmut and adds tests until surviving mutants are killed or justified, then audits dependencies with pip-audit and scans with bandit. Changes no production code; writes only under tests/ and features/, plus .python-dev/mutants-justified.txt.

Internal phase skill, loaded by the implementer subagent; do not trigger directly. Use as the Implementer phase of a Python build: writes pytest unit tests and pytest-bdd step definitions, then production code, until the acceptance scenarios and unit tests pass. Routes to the domain skill named in the brief.

Internal phase skill, loaded by the specifier subagent; do not trigger directly. Use as the Specifier phase of a Python build: turns requirements into pytest-bdd Gherkin acceptance scenarios, marks each trust-boundary crossing with a STRIDE misuse scenario, writes a QA procedure, and produces the component plan for AI and retrieval systems. Writes no production code.

Internal phase skill, loaded by the verifier subagent; do not trigger directly. Use as the Verifier phase of a Python build: in a fresh context, runs the module boundary checks, the eager-import check, pyright, pytest, ruff, and the debt ratchet, then a SIFT audit. Writes no code. Also runs the brownfield debt survey when its TASK is survey.

Use when creating a new Python project or package. Scaffolds with devstart (devstart new <name> -y --python 3.12), falls back to uv init --package when devstart is absent, then applies the python-dev gate overlay so the project passes every phase gate that can run on its first run. A not run result is reported, never counted as a pass. Use for "start project", "scaffold", "new package", or "create CLI".

Use when assessing Python code quality, running an architectural review, or writing a tech advisory report. Applies the SIFT Protocol (Structure, Idioms, Functionality, Testing) with a Toulmin evidence model and weighted rubrics. Four report modes - Full, System Design, Tech Advisory, Backlog. Loaded by the verifier for the SIFT audit.

Use when building a terminal user interface or CLI output in Python: rich for tables, progress, panels, trees, markdown, and logging; questionary for interactive prompts; textual for full-screen reactive apps; pyfiglet for banners; platformdirs for config and cache paths. Loaded by the implementer when the brief names tui, CLI output, prompts, or a terminal app.