lsp-understand

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-understand

Deep-dive exploration of unfamiliar code — given a symbol or file, synthesizes
hover info, implementations, call hierarchy (bounded to 2 levels), all
references, and source into a structured Code Map.

Read-only — does not modify any files.

---

## Differentiation from lsp-explore

`/lsp-explore` is a single-symbol pass: given one symbol name, it runs hover +
implementations + call hierarchy + references and produces a per-symbol report.
Use lsp-explore for quick "what is this one thing" questions.

`/lsp-understand` is broader in three ways:

1. **Accepts a file path as input** — explores all exported symbols in that file
   as a group (Mode B), rather than requiring a single symbol name.
2. **Synthesizes cross-symbol relationships** — produces a dependency map showing
   how entry points call each other, share callers, or implement the same
   interface, rather than isolated per-symbol reports.
3. **Enforces a 2-level call hierarchy depth limit** — prevents infinite recursion
   in deeply connected code.

Use lsp-understand for "how does this module work as a whole."

---

## Input — Two Modes

**Mode A (symbol):** User provides a symbol name in dot notation
(e.g., `"codec.Encode"`, `"Handler.ServeHTTP"`).

**Mode B (file):** User provides an absolute file path. All exported symbols in
the file become the entry points.

---

## Prerequisites

Call `mcp__lsp__get_server_capabilities` before Step 2 to determine which
capabilities are available. Skip steps that require missing capabilities:

- `go_to_implementation`: skip Step 2b if `implementationProvider: false`
- `find_callers`: skip Steps 2c and 2d if `callHierarchyProvider: false`; note
  in the Code Map output that call hierarchy was unavailable

---

## Step 1 — Entry Point Resolution

### Mode A: Single Symbol

Call `mcp__lsp__go_to_symbol` to locate the symbol definition:

```
mcp__lsp__go_to_symbol({
  "symbol_path": "<dot-notation name>",   // e.g. "codec.Encode"
  "workspace_root": "<root>"              // optional
})
→ returns: file_path, line, column (1-indexed)
```

Record `file_path`, `line`, and `column`. If `go_to_symbol` returns nothing,
report:

> Symbol not found: `<name>`
> Check the dot-notation path (e.g. "Package.Symbol") and ensure the workspace
> root covers the file.

Stop immediately — do not proceed to Step 2.

The single symbol becomes the sole entry point.

### Mode B: File Path

Call `mcp__lsp__open_document` then `mcp__lsp__list_symbols`:

```
mcp__lsp__open_document({ "file_path": "<absolute path>" })

mcp__lsp__list_symbols({ "file_path": "<absolute path>" })
→ returns: list of symbols with kind, line, column
```

Filter to exported symbols:
- **Go:** uppercase first letter
- **TypeScript/JavaScript:** `export` keyword
- **Rust:** `pub` visibility

Cap at **10 exported symbols maximum**. If more than 10 are found, prioritize
top-level functions and types; skip constants and variables.

Each filtered symbol becomes an entry point with its `file_path`, `line`, and
`column`.

---

## Step 2 — Per-Symbol Analysis

For each entry point, run the following sub-steps. Where possible, parallelize
calls within each step.

### 2a — Type Info and Docs

Call `mcp__lsp__inspect_symbol` using `position_pattern` with the `@@`
marker (see references/patterns.md):

```
mcp__lsp__inspect_symbol({
  "file_path": "<file>",
  "position_pattern": "<symbol@@name>",
  "line_scope_start": <line - 5>,
  "line_scope_end": <line + 5>
})

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp