lsp-edit-export

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-edit-export

Safe workflow for editing exported symbols. Always discovers all callers before
touching any code, then verifies the change is clean.

## When to Use

Use this skill whenever you intend to change the signature, name, or behavior of
an **exported symbol**: a symbol visible outside its defining package or module.

**Language-specific definitions:**

| 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                                                      |

If you are unsure whether a symbol is exported, treat it as exported and run
this workflow anyway. The cost is a few extra tool calls; the benefit is never
breaking a hidden caller.

**Do NOT skip this workflow** even when you believe there are zero callers.
The confirmation gate in step 3 exists precisely for that case.

## Workflow

**If LSP is not yet initialized**, call `mcp__lsp__start_lsp` with the
workspace root first. (agent-lsp supports auto-inference from file paths, so
explicit start is only required when switching workspaces or on a cold session.)

### Step 1 — Locate the symbol

Use `go_to_symbol` to find the symbol's definition by name, without needing to
know its file path or line number in advance:

```
mcp__lsp__go_to_symbol({
  "symbol_path": "PackageName.ExportedFunction",
  "workspace_root": "/abs/path/to/repo"   // optional, narrows scope
})
```

`symbol_path` uses dot notation. For a top-level function `Encode` in package
`codec`, use `"codec.Encode"`. For a method `Reset` on type `Buffer`, use
`"Buffer.Reset"`. The last component is the leaf name; any prefix is used to
disambiguate when multiple symbols share the same leaf.

The tool returns a `FormattedLocation` with the definition file and 1-indexed
line/column. Record this position — you will need it in step 2.

### Step 2 — Discover all callers

Call `find_references` using the `position_pattern` field to express the cursor
position as a readable text pattern rather than raw coordinates. The `@@` marker
indicates exactly where the cursor sits (the character immediately after `@@`):

```
mcp__lsp__find_references({
  "file_path": "<definition file from step 1>",
  "position_pattern": "func @@ExportedFunction(",
  "include_declaration": false
})
```

The `@@` must immediately precede the first character of the symbol name.
Examples:

- `"func @@Encode("` — Go function declaration
- `"type @@Buffer struct"` — Go type declaration
- `"export function @@parse("` — TypeScript function
- `"class @@Parser:"` — Python class
- `"pub fn @@process("` — Rust function

If `position_pattern` is unavailable on your MCP client, fall back to the
`line` and `column` fields from the location returned in step 1.

The tool returns a list of reference locations across the codebase.

### Step 3 — Confirmation gate (REQUIRED — never skip)

Before making any change, present the impact summary to the user and ask for
explicit confirmation. This gate is mandatory even when the caller count is zero.

Format the gate as follows:

```
## Impact Check: <SymbolName>

- Definition: <file>:<line>
- Callers found: N reference(s) in M file(s)

Files with callers:
  - <file1>
  - <file2>
  ...

Proceed with the edit? [y/n]
```

If the user answers **n**, stop. Do not make any edits.

If the user answers **y**, proceed to step 4.

**Why this gate exists even for 0 callers:** the LSP index may be incomplete
(e.g. files not yet saved, workspace not fully loaded). Zero callers is a data
point, not a guarantee.

### Step 4 — Make the edit

Apply your intended change using `Edit` or `Write`. When replacing a complete
function or method body, `replace_symbol_body` is an option that resolves the
symbol by name and replaces its full range without position math:

```

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp