dependency-resolver

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.

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

When activated, execute these steps autonomously:

Step 1: Collect Local Environment

```bash

# 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:

```bash

# 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:

```bash

# 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:

1. Update .pre-commit-config.yaml with latest versions
2. Run pre-commit autoupdate
3. Regenerate requirements.txt if applicable
4. Stage changes for commit

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.

Pattern 1: Python Minor Version Drift

Symptoms:

• Type errors only in CI
• Import errors with newer syntax
• f-string issues

Fix:

```bash

# 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:

```bash

# Sync pre-commit hooks to latest

pre-commit autoupdate

# Or pin specific version

pip install ruff==

```

Pattern 3: Missing Dependencies

Symptoms:

• ModuleNotFoundError in CI
• Optional dependencies not installed

Fix:

```bash

# Install all optional dependencies

pip install -e ".[dev]"

# Ensure requirements.txt is up to date

pip freeze > requirements.txt

```

````markdown

Environment Comparison

| Component | Local | CI | Status |

| --------- | ------- | ------- | -------- |

| Python | 3.12.10 | 3.11 | MISMATCH |

| ruff | 0.12.7 | 0.13.0 | MISMATCH |

| pyright | 1.1.350 | 1.1.350 | OK |

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

1. 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

```bash

# 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.

````

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

• 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

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