lsp-verify

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-verify: Three-Layer Verification

## When to Use

Run this skill after any significant change to verify correctness at every level:

- After editing source files (logic changes, refactors, new functions)
- After merging or rebasing branches
- After dependency updates or configuration changes
- Before committing or pushing code

## Input

- `workspace_dir` (required): absolute path to the workspace root (e.g. `/Users/you/code/myproject`)
- `changed_files` (optional): list of files you edited — used for targeted diagnostics

## Execution

### Pre-step: Test correlation (when `changed_files` is provided)

Before running the three layers, call `get_tests_for_file` for each changed
source file to build a source → test file map:

```
mcp__lsp__get_tests_for_file({ "file_path": "<changed/source/file>" })
```

Returns the test files that correspond to each source file. Store this map —
it is used in Layer 3 to focus failure analysis. If `changed_files` is unknown,
skip this step.

**Run all three layers in parallel** — they are independent and do not need to
be sequenced. Issue all three calls in the same message to minimize wall time.

### Layer 1: LSP Diagnostics

Call `mcp__lsp__get_diagnostics` with `file_path` set to each changed file.
`get_diagnostics` takes a file path, not a workspace directory.

Note: requires LSP to be initialized. If not yet running, call `start_lsp`
with the workspace root first.

```
mcp__lsp__get_diagnostics({ "file_path": "<path/to/changed/file>" })
```

Call once per changed file. If you don't know which files changed, call it on
the primary files touched in this session. Rank results by severity: errors
first, then warnings.

### Layer 2: Build

```
mcp__lsp__run_build({ "workspace_dir": "<workspace_dir>" })
```

Returns `{ "success": bool, "errors": [...] }`. A failed build means the code
does not compile. Build errors are blocking — must be resolved before shipping.

### Layer 3: Tests

```
mcp__lsp__run_tests({ "workspace_dir": "<workspace_dir>" })
```

Does NOT require `start_lsp`. Returns `{ "passed": bool, "failures": [...] }`.

**Large output warning:** `run_tests` on large repos can return hundreds of
thousands of characters and exceed the context window. If the result is saved
to a file rather than returned inline, do NOT attempt to read the whole file.
Instead, search it for failures:

```bash
grep -E "^(FAIL|--- FAIL)" <output_file>
```

Or scope tests to the correlated test files from the pre-step to avoid the
size issue entirely:

```bash
GOWORK=off go test -count=1 -short ./internal/mypackage/... 2>&1 | grep -E "FAIL|ok"
```

**Using test correlation:** If the pre-step produced a source → test file map,
cross-reference failing test names against that map. For each failure, note
whether it is in a correlated test file (directly covers the changed code) or
an unrelated test file (collateral failure from a shared dependency). This
distinction guides where to investigate first.

Test failures are blocking — they indicate regressions or unmet contracts.

## Output Format

After running all three layers, produce a structured report:

```
## Verification Report

### Layer 1: LSP Diagnostics
[CLEAN / N errors, M warnings]

<details if N > 0 or M > 0>
Errors:
- file:line - message

Warnings:
- file:line - message
</details>

### Layer 2: Build
[PASSED / FAILED - N errors]

<details if FAILED>
- error message (file:line)
</details>

### Layer 3: Tests

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp