lsp-dead-code

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-dead-code

Audit an exported symbol list for zero-reference candidates. Calls
`list_symbols` to enumerate symbols, then checks each exported
symbol with `find_references` to find callers. Produces a classified report.

## When to Use

Use this skill when you want to identify dead code in a file — exported
symbols that are defined but never called anywhere in the workspace. Common
use cases:

- Cleaning up APIs before a release
- Identifying legacy exports that can be safely removed
- Auditing a package for unused public surface area

**Important:** This skill surfaces *candidates*. Always review results
manually before deleting anything. See the Caveats section below.

## What counts as "exported"

| Language   | Exported means...                                                      |
|------------|------------------------------------------------------------------------|
| Go         | Identifier starts with an uppercase letter (e.g. `MyFunc`, `MyType`)  |
| TypeScript | Has `export` keyword; or is a public class member (no `private`)       |
| Python     | Not prefixed with `_`; or explicitly listed in `__all__`               |
| Java/C#    | Has `public` or `protected` visibility modifier                        |
| Rust       | Has `pub` keyword                                                      |

## Prerequisites

If LSP is not yet initialized, call `mcp__lsp__start_lsp` with the
workspace root first:

```
mcp__lsp__start_lsp({ "root_dir": "/your/workspace" })
```

agent-lsp supports auto-inference from file paths, so explicit start is
only required when switching workspaces or on a cold session.

## Step 0 — Verify indexing is complete (mandatory)

**Do not skip this step.** An under-indexed workspace returns `[]` for
symbols that ARE referenced, producing false dead-code candidates.

Pick one symbol you know is actively used (e.g. the primary constructor,
a widely-called utility function). Call `find_references` on it:

```
mcp__lsp__find_references({
  "file_path": "/abs/path/to/file.go",
  "line": <known-active symbol line>,
  "column": <known-active symbol column>,
  "include_declaration": false
})
```

**If this returns `[]`:** the workspace is not indexed. Wait 3–5 seconds
and retry. Do not proceed until a known-active symbol returns ≥1 reference.
If it never returns results after 15 seconds, restart the LSP server with
`mcp__lsp__restart_lsp_server` and re-open the target file.

## Step 1 — Open the file and enumerate symbols

Open the file so the language server tracks it, then fetch all symbols:

```
mcp__lsp__open_document({ "file_path": "/abs/path/to/file.go" })

mcp__lsp__list_symbols({ "file_path": "/abs/path/to/file.go" })
```

Collect the full symbol list. Filter to **exported symbols only** using the
language-appropriate rule from the table above.

**Coordinate note:** `list_symbols` returns 1-based coordinates.
Pass `selectionRange.start.line` and `selectionRange.start.character`
directly to `find_references` — no conversion needed.

**"no identifier found" error:** This means the column points to whitespace
or a keyword rather than the identifier name. This happens with methods
whose receiver prefix shifts the name rightward (e.g. `func (c *Client) MethodName`
— the name starts at column 21, not column 1). Fix: grep the declaration
line for the symbol name to find its exact column:

```
grep -n "MethodName" file.go
# count characters to find the 1-based column of the name
```

Then retry `find_references` with the corrected column.

## Step 2 — Check references for each exported symbol

For each exported symbol, call `find_references` with
`include_declaration: false` so the definition site itself is excluded
from the count. A count of 0 means no callers, not no occurrences.

```
mcp__lsp__find_references({
  "file_path": "/abs/path/to/file.go",
  "line": <selectionRange.start.line>,
  "column": <selectionRange.start.character>,
  "include_declaration": false
})
```

Record the result for each symbol:
```
{ symbol_name, kind, line, reference_count, locations[] }
```

**Batching note:** For files with many exported symbols (>20), process in
batches of 5–10 to avoid overwhelming the LSP server.

**Zero-reference cross-check (required before classifying as dead):**

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp