Dependency Resolver Skill

Purpose

This skill detects and resolves local vs CI environment mismatches BEFORE push, preventing the 20-45 minute debug cycles documented in DISCOVERIES.md ("CI Failure Resolution Process Analysis" entry).

The skill addresses a critical gap: existing tools (ci-diagnostic-workflow, pre-commit-diagnostic) fix issues AFTER they occur. This skill catches mismatches BEFORE push.

Problem Statement

From DISCOVERIES.md analysis:

• Environment mismatches (Local Python 3.12 vs CI Python 3.11) cause 20-25 min investigation overhead

• Version drift (local ruff 0.12.7 vs CI ruff 0.13.0) causes silent failures

• 45-minute complex debugging sessions traced to dependency conflicts

• No automated pre-push environment comparison exists

Execution Instructions

When activated, execute these steps autonomously:

Step 1: Collect Local Environment

Python version

python --version

Installed tool versions

pip show ruff black pyright mypy 2>/dev/null | grep -E "^(Name|Version):"

Pre-commit hook versions (if available)

cat .pre-commit-config.yaml 2>/dev/null | grep -E "rev:|repo:"

Step 2: Read CI Configuration

Read(file_path=".github/workflows/ci.yml") Read(file_path="pyproject.toml") Read(file_path=".pre-commit-config.yaml")

Extract:

• CI Python version (look for python-version: )

• Required tool versions from pyproject.toml

• Pre-commit hook versions from .pre-commit-config.yaml

Step 3: Compare Environments

Build comparison table:

Component Local CI Status

Python 3.12.10 3.11 MISMATCH

ruff 0.12.7 0.13.0 MISMATCH

black 24.3.0 24.3.0 OK

Step 4: Generate Recommendations

For each mismatch, provide actionable fix:

Python Version Mismatch:

Option A: Use pyenv to match CI version

pyenv install 3.11 pyenv local 3.11

Option B: Update CI to match local (if local is intentional)

Edit .github/workflows/ci.yml line 33

Tool Version Mismatch:

Pin versions in pyproject.toml

pip install ruff==0.13.0

Or update pre-commit hooks

pre-commit autoupdate

Step 5: Auto-Fix (When Requested)

If user requests auto-fix:

• Update .pre-commit-config.yaml with latest versions

• Run pre-commit autoupdate

• Regenerate requirements.txt if applicable

• Stage changes for commit

Integration Points

With fix-agent

Integrates with fix-agent templates for:

• Import/dependency fixes (Template 1)

• Configuration fixes (Template 2)

• CI/CD fixes (Template 4)

With pre-commit-diagnostic

Hand-off when pre-commit failures detected after version sync.

With ci-diagnostic-workflow

Hand-off for post-push CI failures not caught by pre-push validation.

Common Mismatch Patterns

Pattern 1: Python Minor Version Drift

Symptoms:

• Type errors only in CI

• Import errors with newer syntax

• f-string issues

Fix:

Check CI Python version

grep -r "python-version" .github/workflows/

Match locally or update CI

Pattern 2: Linter Version Drift

Symptoms:

• "Works locally but CI fails on linting"

• New rules in CI not enforced locally

• Formatting differences

Fix:

Sync pre-commit hooks to latest

pre-commit autoupdate

Or pin specific version

pip install ruff==<ci-version>

Pattern 3: Missing Dependencies

Symptoms:

• ModuleNotFoundError in CI

• Optional dependencies not installed

Fix:

Install all optional dependencies

pip install -e ".[dev]"

Ensure requirements.txt is up to date

pip freeze > requirements.txt

Output Format

Dependency Resolver Report

Environment Comparison

Mismatches Found: 2

Recommendations

1. Python Version (CRITICAL)

   • Local: 3.12.10, CI: 3.11
   • Action: Consider using pyenv to test with CI version before push
   • Risk: Type syntax differences may cause failures

2. ruff Version (WARNING)

   • Local: 0.12.7, CI: 0.13.0
   • Action: Run pip install ruff==0.13.0 or pre-commit autoupdate
   • Risk: New rules may flag previously passing code

Quick Fix Commands

# Sync ruff version
pip install ruff==0.13.0

# Update all pre-commit hooks
pre-commit autoupdate

# Re-run pre-commit to validate
pre-commit run --all-files

Status: ACTION REQUIRED

Push may fail due to environment mismatches. Run recommended fixes before pushing.

When to Use This Skill

Trigger Signs:

• "CI is failing but it works locally"

• "Linting passes here but not in CI"

• Before pushing after long development session

• After updating local Python or tools

• When onboarding to new project

Not Needed When:

• CI already passing consistently

• Environment just synced

• Only editing documentation

Related Resources

• DISCOVERIES.md: CI Failure Resolution Process Analysis (lines 836-914)

• fix-agent.md: Templates for import/config/CI fixes

• ci-diagnostic-workflow.md: Post-push CI failure resolution

• pre-commit-diagnostic.md: Pre-commit hook failures

• .github/workflows/ci.yml: CI configuration source of truth

Philosophy Alignment

Ruthless Simplicity

• Procedural approach: Five clear steps, no unnecessary abstraction

• Direct shell commands: Users can copy-paste recommendations

• Focused scope: Only detects environment mismatches, delegates fixes to existing agents

Zero-BS Implementation

• Actionable output: Every recommendation includes exact commands

• No theoretical advice: Specific version numbers and file paths

• Pre-push prevention: Catches issues before wasted CI cycles

Modular Design

• Clean hand-offs: Integrates with fix-agent, pre-commit-diagnostic, ci-diagnostic-workflow

• Single responsibility: Detection and comparison only; fixes delegated to specialized agents

• Regeneratable: Can be rebuilt from this specification