lsp-refactor

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-refactor

End-to-end safe refactor workflow. Sequences blast-radius analysis, speculative
preview, disk apply, build verification, and targeted test execution in one
coordinated pass.

**This skill does NOT replace lsp-safe-edit or lsp-impact.**
- `lsp-safe-edit` wraps a single edit with before/after diagnostic comparison —
  use it when you need to make one targeted change with careful error diffing.
- `lsp-impact` is read-only blast-radius analysis — use it when you want to
  understand scope before deciding whether to proceed.
- `lsp-refactor` sequences ALL four workflows (lsp-impact → lsp-safe-edit →
  lsp-verify → lsp-test-correlation) in order. Use it when you know your target
  and intent up front and want the complete workflow without switching skills.

---

## Input

- **target**: symbol name in dot notation (e.g. `"codec.Encode"`, `"Buffer.Reset"`)
  OR file path (e.g. `"internal/lsp/client.go"`)
- **intent**: description of the change to make (e.g. "rename to ParseConfigV2",
  "add a second parameter `timeout time.Duration`")
- **workspace_root**: absolute path to the workspace root

---

## Phase 1 — Blast-Radius Analysis (inlined from lsp-impact)

**This phase is mandatory. Do not skip it, even for "small" refactors.**

Call `mcp__lsp__blast_radius` with `changed_files` set to the file
containing the target symbol. If the user provided a file path directly, use it.
If the user provided a symbol name, resolve the file first (e.g. via
`mcp__lsp__go_to_symbol`).

```
mcp__lsp__blast_radius({
  "changed_files": ["/abs/path/to/file"],
  "include_transitive": false
})
```

Returns:
- `affected_symbols` — exported symbols with reference counts
- `test_callers` — test files and enclosing test function names
- `non_test_callers` — production call sites

**Display:**
- Affected symbol count
- Test callers (each with enclosing test function name)
- Non-test callers (each with file:line)
- Total reference count

**High blast-radius gate:** If the total reference count exceeds 20, STOP and
ask the user to confirm before continuing:

```
High blast radius: N callers found. Proceed with refactor? [y/n]
```

If the user answers "n", abort. Do not proceed to Phase 2.

---

## Phase 2 — Speculative Preview (inlined from lsp-safe-edit)

Only reached if Phase 1 blast radius is acceptable (≤ 20 callers, or user confirmed).

### 2a — Open file and capture baseline diagnostics

```
mcp__lsp__open_document({ "file_path": "/abs/path/to/file", "language_id": "go" })
mcp__lsp__get_diagnostics({ "file_path": "/abs/path/to/file" })
```

Store baseline diagnostics as BEFORE.

### 2b — Speculative simulation

For a **single-file change**: use `preview_edit`:

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

For a **multi-file change** (e.g. rename + call site updates): use `simulate_chain`:

```
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 ...
  ]
})
```

### 2c — Evaluate simulation result

Display the speculative result using the Diagnostic Diff Output Format from
[references/patterns.md](references/patterns.md).

**Decision:**

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp