dependency-resolver

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:

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

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

| 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

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

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

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