python-quality-and-cli

name	python-quality-and-cli
description	Use when implementing or refactoring Python in [ORG_NAME] product code or repo scripts: CLI design (argparse/Typer), exit codes, logging, pathlib, typing, pytest, and Ruff/Mypy per pyproject.toml.

Python quality & CLI (Engineering)

When to use

• Any Python change under [PRODUCT_CODE_ROOT]/ (API, packages, scripts, tests).
• CLI tools (scripts/, __main__, maintenance utilities).
• Reviews of “simple mistakes” (print vs log, bare except, weak CLI UX, missing encodings).

Canonical references

1. [PRODUCT_CODE_ROOT]/docs/engineering/PYTHON_LAW_v1.md — locked law (layers, contracts, scripts, tooling, learn-as-you-go).
2. shared_context/python_agent_coding_hygiene_v1.md — supplementary habits + founder link map.
3. [PRODUCT_CODE_ROOT]/pyproject.toml — [tool.ruff], [tool.mypy], dependencies.
4. .cursor/rules/method-python-law.mdc — applies when editing [PRODUCT_CODE_ROOT]/**/*.py.
5. Neighbors in [PRODUCT_CODE_ROOT]/services/api/, [PRODUCT_CODE_ROOT]/packages/, [PRODUCT_CODE_ROOT]/tests/ — match local patterns; golden pair: services/api/routes/ingest.py + services/api/ingest.py.

CLI rules of thumb

Topic	Guidance
Parser	argparse unless repo already uses Typer/Click for that entrypoint.
Help	--help accurate; subcommands documented.
Exit codes	0 ok; non-zero on error; parse errors → 2 (argparse default).
Validation	Ports, paths, choices — at parse time when possible.
Output	User messages to stdout; errors to stderr for scriptability.

Quality gates before merge

# From [PRODUCT_CODE_ROOT]/ package root (adjust if monorepo docs say otherwise)
python -m pytest
ruff check .
mypy .   # if configured for scope you touched

AI / ML code

• TensorFlow (tensorflow.org) only when TF is a declared dependency and task requires it.
• Default stack: Python stdlib HTTP (product API), llama.cpp lanes (inference/embed), pytest — keep model boundaries thin and testable.

Anti-patterns (fix on sight)

• Silent except: pass
• Secrets or tokens in code
• print() in shared library paths instead of logging
• CLI with no --help or misleading help text
• Assuming current working directory without documenting it

Related skills

• session-notes/SKILL.md — log session outcomes after larger refactors.
• gate-check/SKILL.md — gate evidence when changes touch release criteria.