lsp-edit-export

name	lsp-edit-export
description	Safe workflow for editing exported symbols or public APIs. Use when changing a function signature, modifying a public type, or altering any symbol used outside its own package — finds all callers first so nothing breaks silently.
argument-hint	[symbol-name]
user-invocable	true
allowed-tools	mcp__lsp__go_to_symbol mcp__lsp__open_document mcp__lsp__find_references mcp__lsp__get_diagnostics mcp__lsp__run_build mcp__lsp__replace_symbol_body Edit Write
license	MIT
compatibility	Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
metadata	{"required-capabilities":"referencesProvider","optional-capabilities":"workspaceSymbolProvider"}

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:

mcp__lsp__replace_symbol_body({
  "file_path": "<definition file>",
  "symbol_path": "ExportedFunction",
  "new_body": "<new full definition>"
})

For other edits (signature changes, partial modifications), use Edit or Write. Follow the standard edit workflow for the language. If renaming, update all call sites identified in step 2 as well; do not leave broken callers.

Collect diagnostics before the edit so you have a baseline for comparison in step 5:

mcp__lsp__get_diagnostics({
  "file_path": "<definition file>"
})

Then apply the edit and collect diagnostics again after.

Step 5 — Check diagnostics

Compare before and after diagnostic snapshots using the format in references/patterns.md.

If new errors appear, fix them before proceeding. Do not run the build with known diagnostic errors outstanding.

Step 6 — Run the build

mcp__lsp__run_build({
  "workspace_root": "/abs/path/to/repo"
})

A clean build confirms no compilation errors across all affected packages. If the build fails, diagnose using the error output and diagnostic data from step 5. Fix and re-run until the build passes.

Step 7 — Report

Emit the final output block:

## Edit Summary
- Symbol: <name> (<kind>)
- Callers found: N in M files
- Diagnostics: net +N/-N
- Build: PASSED / FAILED

If build is FAILED, include the first 3–5 error lines and a brief diagnosis.

Example

Goal: rename exported function `ParseConfig` → `LoadConfig` in pkg/config

Step 1 — go_to_symbol: symbol_path="config.ParseConfig"
  → pkg/config/parser.go:42:6

Step 2 — find_references: position_pattern="func @@ParseConfig("
  → 7 references in 4 files

Step 3 — gate:
  ## Impact Check: ParseConfig
  - Definition: pkg/config/parser.go:42
  - Callers found: 7 in 4 files
  Files: cmd/main.go, internal/app.go, internal/loader.go, pkg/config/parser_test.go
  Proceed? [y/n] → y

Step 4 — edit: rename declaration + all 7 call sites

Step 5 — diagnostics: net 0 (no new errors)

Step 6 — build: PASSED

Step 7 — report:
  ## Edit Summary
  - Symbol: LoadConfig (function)
  - Callers found: 7 in 4 files
  - Diagnostics: net 0
  - Build: PASSED

Note on position_pattern

position_pattern with @@ is a agent-lsp extension. If your MCP client or server does not support it, fall back to explicit line and column parameters from the location returned by go_to_symbol in step 1.