lsp-rename

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-rename: Safe Symbol Rename

Renames a symbol across the workspace in two phases: preview first, then execute
only after explicit confirmation. Never renames without showing impact.

**Invocation:** User provides `old_name` (the symbol to rename) and `new_name`
(the replacement). Optionally provide `workspace_root` to scope the search.

---

## Prerequisites

If LSP is not yet initialized, call `mcp__lsp__start_lsp` with the workspace
root first. Auto-inference applies when file paths are provided, but an explicit
start is required when switching workspaces.

---

## Phase 1: Preview

Find the symbol, enumerate all references, and produce a dry-run preview.
**Do not apply any edits in this phase.**

### Step 1 — Locate the symbol

Call `mcp__lsp__go_to_symbol` with `symbol_path` set to `old_name`:

```
mcp__lsp__go_to_symbol
  symbol_path: "old_name"        # or "Package.OldName" for qualified paths
  workspace_root: "<root>"       # optional; omit to search entire workspace
```

This returns the definition location (file, line, column). If not found, report
the error and stop.

### Step 2 — Validate rename is possible

Call `mcp__lsp__prepare_rename` at the definition location from Step 1:

```
mcp__lsp__prepare_rename
  file_path: "<file from Step 1>"
  line: <line from Step 1>
  column: <column from Step 1>
```

`prepare_rename` asks the language server whether a rename is valid at this
position. If it returns an error (e.g. the symbol is a keyword, a built-in, or
in a location the server cannot rename), **stop immediately** and report:

> Cannot rename `OldName`: <server error message>
> Common causes: built-in or keyword, imported external package, or position is
> not on the symbol name. Try locating the declaration site directly.

Only proceed to Step 3 if `prepare_rename` succeeds.

### Step 3 — Enumerate references

Call `mcp__lsp__find_references` at the definition location from Step 1:

```
mcp__lsp__find_references
  file_path: "<file from Step 1>"
  position_pattern: "<symbol>@@"   # @@ immediately after the symbol name
  # fallback: use line/column from Step 1 if position_pattern is unavailable
```

Collect all returned locations. Note the total count and the distinct files.

### Step 4 — Dry-run preview

Call `mcp__lsp__rename_symbol` with `dry_run=true`. **Do not call `apply_edit`.**

```
mcp__lsp__rename_symbol
  file_path: "<file from Step 1>"
  line: <line from Step 1>
  column: <column from Step 1>
  new_name: "<new_name>"
  dry_run: true
```

The response includes a `workspace_edit` with all proposed changes and a
`preview.note` describing the scope.

### Step 5 — Report impact and hard stop

Display the preview summary to the user:

```
Rename preview: OldName -> NewName
  Locations to update: N (from find_references count)
  Files affected:      M (distinct files in workspace_edit)
  Language server:     <gopls | typescript-language-server | rust-analyzer | ...>

Changes:
  path/to/file1.go  lines 12, 45, 78
  path/to/file2.go  line 3
  ...
```

**REQUIRED hard stop — do not proceed without explicit user confirmation:**

> Proceed with rename? [y/n]

Wait for user input. Do not apply any edit until the user answers "y" or "yes".

---

## Edge Case: 0 References

If `find_references` returns an empty list (the symbol exists but has no external
usages), warn the user before stopping:

> Warning: no references found for `OldName`. The symbol may be unexported,
> dead code, or the LSP index may be stale. Renaming will update only the

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp