Troubleshooting

Problemas Comunes

Problema	Causa	Solucion
ModuleNotFoundError: {PACKAGE_NAME}	Paquete no instalado en modo editable	pip install -e ".[dev]"
ruff no encuentra archivos	Path incorrecto	Verificar que src/ existe
mypy errores de imports	Dependencias sin stubs	pip install types-<paquete> o --ignore-missing-imports
pytest no encuentra tests	Falta __init__.py o estructura incorrecta	Verificar estructura tests/unit/
Pre-commit falla	Hooks no instalados	pre-commit install
Import circular	Dependencia ciclica entre modulos	Extraer a modulo compartido o usar TYPE_CHECKING

Dependencias Criticas (versiones fijadas)

Dependencia	Version	Nota
Python	{PYTHON_VERSION}	Version del proyecto
ruff	>=0.4.0	Linter + formatter
mypy	>=1.10.0	Type checker
pytest	>=8.0	Test framework
returns	>=0.22.0	Result pattern

Debugging de CI

Si el CI falla pero local funciona:

1. Verificar version de Python (CI usa env.PYTHON_VERSION)
2. Verificar dependencias instaladas (pip install -e ".[dev]")
3. Revisar ruff config en pyproject.toml (line-length, target-version)
4. Verificar mypy strict mode (puede fallar en stubs faltantes)