lsp-safe-edit

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-safe-edit

Wrap any code edit with a before/after diagnostic comparison. Speculatively
previews the change in-memory before touching disk, then diffs errors introduced
vs. resolved after applying. If errors appear, surfaces code actions to fix them.

## Prerequisites

LSP must be running for the target workspace. If not yet initialized, call
`mcp__lsp__start_lsp` with the workspace root before proceeding.

Auto-init note: agent-lsp supports workspace auto-inference from file paths.
Explicit `start_lsp` is only needed when switching workspace roots.

## Input

- **target file(s):** One or more files to be edited (absolute paths).
- **description of change:** What you intend to edit and why.

---

## Workflow

### Step 1 — Open target file(s)

Call `mcp__lsp__open_document` for each file that will be edited:

```
mcp__lsp__open_document(file_path: "/abs/path/to/file.go", language_id: "go")
```

### Step 2 — Capture baseline diagnostics (BEFORE)

Call `mcp__lsp__get_diagnostics` for each target file. Store as BEFORE.
For multi-file edits, collect diagnostics for all files involved.

```
BEFORE = mcp__lsp__get_diagnostics(file_path: "/abs/path/to/file.go")
```

If the server returns an empty list immediately after open, wait briefly and
retry — LSP analysis is async.

### Step 3 — Speculative preview (preview_edit)

Before touching disk, call `mcp__lsp__preview_edit` to preview the
error delta of the intended change:

```
mcp__lsp__preview_edit(
  file_path: "/abs/path/to/file.go",
  start_line: <N>,
  start_column: <col>,
  end_line: <N>,
  end_column: <col>,
  new_text: "<replacement text>"
)
```

Returns `net_delta` (new errors introduced minus errors resolved) without
writing to disk.

**Decision:**

| `net_delta` | Action |
|-------------|--------|
| ≤ 0 | Proceed — edit improves or does not worsen error state |
| > 0 | **Pause.** Report introduced errors to user and ask: "Proceed anyway? [y/n]" |

If `net_delta > 0` and user says "n", stop. Do not apply the edit.

**Multi-file edits:** `preview_edit` covers one file at a time. For
edits spanning multiple files, run it for each file independently and sum the
deltas. If any file shows `net_delta > 0`, pause before continuing.

**When to skip Step 3:** If the intended change is a new file (Write), there is
no existing file to simulate against. Skip to Step 4.

### Step 3b — Refactor preview with simulate_chain (renames and signature changes)

Use this step **instead of or after** Step 3 when the change is a rename,
signature change, or any edit with dependent follow-on edits (e.g., updating
all call sites after adding a parameter).

`simulate_chain` applies a sequence of speculative edits in-memory and reports
whether the cumulative change is safe — without touching disk:

```
mcp__lsp__simulate_chain({
  "workspace_root": "/abs/path/to/workspace",
  "language": "go",
  "edits": [
    {
      "file_path": "/abs/path/to/file.go",
      "start_line": <N>, "start_column": <col>,
      "end_line": <N>,   "end_column": <col>,
      "new_text": "<replacement>"
    },
    // additional dependent edits (e.g. call site updates) ...
  ]
})
```

Returns:
- `cumulative_delta` — net error change across all steps
- `safe_to_apply_through_step` — how many steps are safe to apply in sequence

**Decision:**

| `cumulative_delta` | `safe_to_apply_through_step` | Action |
|--------------------|------------------------------|--------|
| ≤ 0 | = total steps | All steps safe. Proceed to Step 4. |
| ≤ 0 | < total steps | Safe up to that step. Review remaining steps. |
| > 0 | any | Net regression. Report to user before proceeding. |

**When to use Step 3b:**
- Renaming an exported symbol and updating its call sites

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp