---
name: references
description: Find all references to a symbol using LSP. Shows everywhere a function, class, or variable is used.
---

# Find References Skill

## Description

This skill uses Language Server Protocol (LSP) to find all references to a symbol across the codebase. It's essential for understanding symbol usage before refactoring.

## Prerequisites

Requires LSP servers to be installed:
- **Python**: `pip install python-lsp-server`
- **JavaScript/TypeScript**: `npm install -g typescript-language-server typescript`
- **C/C++**: Install clangd from LLVM

## When to Use

- When the user asks "where is X used?"
- Before renaming a function/variable
- When assessing refactoring impact
- When understanding how a function is called

## How to Use

### Step 1: Identify the Symbol

Find the file and position of the symbol to search for.

### Step 2: Query References

Use the `lsp_find_references` tool:

```python
lsp_find_references(
    file_path="src/utils.py",
    line=15,  # 0-indexed
    character=4,  # 0-indexed
    include_declaration=True,  # Include the definition itself
    workspace="."
)
```

### Step 3: Present Results

Show all locations where the symbol is used, grouped by file.

## Examples

### Example 1: Find All Usages Before Refactoring

**User Request:** "Find all usages of `calculate_total` before I rename it"

**Approach:**
1. Find the function definition
2. Call `lsp_find_references` at that position
3. List all files and line numbers where it's used
4. Count total references for impact assessment

### Example 2: Check If Function Is Used

**User Request:** "Is `legacy_handler` still being used anywhere?"

**Approach:**
1. Find the function definition
2. Call `lsp_find_references` with `include_declaration=False`
3. If empty, the function is unused (dead code)
4. If not empty, show where it's still used

### Example 3: Understand API Usage

**User Request:** "How is the User class being used in this codebase?"

**Approach:**
1. Find the User class definition
2. Get references to the class name
3. Categorize usages: instantiation, inheritance, type hints
4. Summarize the usage patterns

## Output Format

```json
{
  "success": true,
  "count": 12,
  "references": [
    {"file": "/path/to/main.py", "line": 10, "character": 15},
    {"file": "/path/to/test.py", "line": 25, "character": 8},
    {"file": "/path/to/utils.py", "line": 5, "character": 0}
  ]
}
```

## Combining with Other Tools

### Safe Rename Workflow

1. Find references with `lsp_find_references`
2. Review all usages
3. Make the rename
4. Verify no references were missed

### Dead Code Detection

1. Get all function definitions from `analyze_project`
2. For each function, check if `lsp_find_references` returns any usages
3. Functions with no references (except declaration) are likely dead code

## Notes

- Use `include_declaration=False` to exclude the definition itself
- Cross-file references require the workspace to be indexed
- May take longer on large codebases (first query initializes the server)
- Some dynamic usages (eval, getattr) may not be detected
