environment-triage

Environment Triage

⭐2.2kstars🔀157forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

The Environment Triage skill is a specialized diagnostic utility designed to resolve Python interpreter mismatches and package installation failures. It provides a systematic approach to debugging development environments, specifically focusing on modern tooling like 'uv' and 'pip'. By verifying the active interpreter, checking .python-version configurations, and validating imports, it ensures that developers can quickly identify and fix environment-related bottlenecks that hinder productivity.

Use Cases

  • Case 1: Resolving 'ModuleNotFoundError' when a package appears to be installed but cannot be imported by the active script.
  • Case 2: Fixing dependency conflicts where a project requires Python 3.12+ but the local environment or uv is defaulting to an older version.
  • Case 3: Verifying the integrity of virtual environments after running sync commands to ensure the correct interpreter is being utilized.
  • Case 4: Troubleshooting 'it works on my machine' issues by auditing the specific .python-version and venv settings used by the agent or developer.
nameenvironment-triage
descriptionEnvironment Triage
user-invocablefalse

Environment Triage

When uv sync or pip install behaves unexpectedly, check the actual interpreter.

Pattern

System Python is not authoritative if uv/venv selects a different interpreter.

DO

# What uv ACTUALLY uses
uv run python --version

# What's pinned (this controls uv)
cat .python-version

# Confirm package is installed
uv pip show <package>

# Confirm import works in uv context
uv run python -c "import <package>; print(<package>.__version__)"

Common Fix

If optional deps require Python 3.12+ but .python-version is 3.11:

echo "3.13" > .python-version
rm -rf .venv && uv venv && uv sync --all-extras

DON'T

  • Trust python3 --version when using uv
  • Assume install succeeded without verifying import
  • Debug further before checking interpreter version

Source Sessions

  • 2243c067: symbolica-agentica skipped due to python_version >= 3.12 marker, but uv was using 3.11
  • 4784f390: agentica import failures traced to wrong interpreter