---
name: deps
description: Analyze import/include dependencies between files. Detects circular dependencies and shows dependency trees.
---

# Dependency Analysis Skill

## Description

This skill analyzes import and include relationships between source files. It identifies which modules depend on which, detects circular dependencies, and can show dependency trees.

## When to Use

- When the user asks "what does this file depend on?"
- When looking for circular dependencies
- When planning refactoring to understand module boundaries
- When the user wants to see import relationships

## How to Use

### Step 1: Choose Analysis Scope

Single file or entire directory.

### Step 2: Run Dependency Analysis

Use the `analyze_dependencies` tool:

```python
# Analyze directory
analyze_dependencies(path="src/")

# Focus on specific file
analyze_dependencies(
    path="src/",
    focus_file="src/main.py"
)

# Generate diagram
analyze_dependencies(
    path="src/",
    output_format="mermaid"
)
```

### Step 3: Interpret Results

Key outputs:
- `imports`: What this file imports
- `imported_by`: Who imports this file
- `circular_dependencies`: Problematic cycles
- `external_dependencies`: Third-party packages

## Examples

### Example 1: Find Circular Dependencies

**User Request:** "Are there any circular imports?"

**Approach:**
1. Call `analyze_dependencies(path=".")`
2. Check `circular_dependencies` in result
3. If found, explain the cycle and suggest fixes

### Example 2: Module Dependency Tree

**User Request:** "What does auth.py depend on?"

**Approach:**
1. Call `analyze_dependencies(path=".", focus_file="src/auth.py")`
2. Show the `dependency_tree`
3. List direct and transitive dependencies

### Example 3: Impact Analysis

**User Request:** "If I change utils.py, what else is affected?"

**Approach:**
1. Call `analyze_dependencies(path=".", focus_file="src/utils.py")`
2. Show `imported_by` list - these files will be affected
3. Show reverse dependency tree for full impact

## Output Formats

### Summary (JSON)
```json
{
  "total_files": 15,
  "total_dependencies": 28,
  "external_dependencies": ["requests", "pandas", "numpy"],
  "circular_dependencies": [
    ["src/a.py", "src/b.py"]
  ],
  "focus": "src/main.py",
  "imports": ["src/auth.py", "src/utils.py"],
  "imported_by": []
}
```

### Mermaid
```mermaid
graph LR
    main --> auth
    main --> utils
    auth --> db
    utils --> config
```

## Handling Circular Dependencies

When circular dependencies are detected:

1. **Identify the cycle**: Show which files form the loop
2. **Analyze the cause**: Usually shared types or utilities
3. **Suggest solutions**:
   - Extract shared code to a new module
   - Use dependency injection
   - Delay imports (import inside function)

## Notes

- External dependencies are packages not in the codebase
- Relative imports are resolved to module names
- Use Mermaid output for documentation
- Circular deps often indicate architecture issues
