diagnose-python-project

Diagnose Python Project

Purpose

Find the first meaningful cause of a Python failure and explain it in human terms.

The useful answer is not "tests failed." It is what command failed, which project or package failed, which phase failed, why it most likely failed, and the smallest next check or fix.

When To Use

• Use this skill when uv sync, uv run pytest, uv run ruff, uv run mypy, package build checks, FastAPI startup, or FastMCP startup fails.
• Use this skill when Python version selection, dependency groups, lockfiles, package layout, imports, test discovery, or type checking are unclear.
• Use this skill before widening into refactors after a vague Python error.

Source Check

Use repo-local files, checked-out dependency sources, Dash MCP or Dash HTTP for installed docsets, and then official project documentation when Dash/local coverage is missing or stale:

• uv documentation
• pytest documentation
• Ruff documentation
• mypy documentation
• Python packaging user guide
• FastAPI documentation
• FastMCP documentation

Diagnostic Workflow

1. Capture repository shape:

   rg --files -g 'pyproject.toml' -g 'uv.lock' -g '.python-version' -g 'requirements*.txt' -g 'setup.py' -g 'setup.cfg' -g 'tox.ini' -g 'noxfile.py' -g '*.py'
   

2. Identify the exact failing command.
3. Re-run only the narrowest failing command when reproduction is needed.
4. Classify the failure phase:
   • Python version
   • dependency resolution
   • lockfile sync
   • import or package layout
   • test discovery
   • test execution
   • lint
   • format
   • type check
   • FastAPI startup
   • FastMCP startup
   • package build
   • CI environment
5. Identify the first meaningful error.
6. Explain the likely cause and smallest next check.

Common Failure Classes

Python Version

Look for requires-python, .python-version, CI setup, and uv interpreter selection.

Report when the repo asks for a Python version that local or CI does not provide.

Dependency Resolution

Look for dependency groups, optional dependencies, extras, index configuration, lockfile drift, and private package sources.

Do not turn authenticated index failures into generic network diagnoses. Name the package source or credential surface when visible.

Imports And Package Layout

Separate installed-package import failures from test-context import failures.

For src/ layouts, check whether commands run through uv with the package installed. For workspaces, check whether the command targets the intended package member.

Test Discovery And Execution

Discovery failures usually point at package imports, pytest configuration, plugin availability, markers, or test file naming.

Execution failures usually point at behavior, fixtures, environment, timing, async boundaries, or external dependencies.

Ruff

Separate lint failures from format failures.

Use uv run ruff check . for lint and uv run ruff format --check . only when the repo enforces formatting.

mypy

Check configuration scope, missing stubs, optional dependencies, package exports, and Python-version settings before suppressing errors.

FastAPI And FastMCP

Check import paths, app object names, lifespan handling, settings loading, dependency initialization, and environment variables.

For combined FastAPI/FastMCP apps, verify that mounted app lifespan behavior was preserved.

Output Shape

Return:

1. Command: exact failing command.
2. Phase: failure phase.
3. Project: package, workspace member, app, or workflow involved.
4. First meaningful error: short quoted or paraphrased error.
5. Likely cause: concrete explanation.
6. Next check: one or two smallest useful commands or edits.

Guardrails

• Do not bury the first meaningful error under a long transcript.
• Do not rerun broad commands repeatedly before narrowing the phase.
• Do not delete lockfiles, virtual environments, caches, or generated artifacts without explaining why and getting approval when destructive.
• Do not add sys.path hacks to hide package-layout problems.
• Do not suppress Ruff or mypy findings to make checks pass unless the suppression is intentional and documented.