lsp-enable

What this skill does

# LSP-First Code Intelligence

## The Iron Laws

```
1. NO MODIFYING UNFAMILIAR CODE WITHOUT goToDefinition FIRST
2. NO REFACTORING WITHOUT findReferences IMPACT ANALYSIS FIRST
3. NO CLAIMING CODE WORKS WITHOUT LSP DIAGNOSTICS VERIFICATION
```

Violating these laws wastes tokens, introduces bugs, and produces incomplete changes.

## Trigger Phrases

Activate when user says:

- "find definition", "go to definition", "where is X defined"
- "find references", "who uses this", "what calls this function"
- "understand this code", "trace this function", "explore codebase"
- "before I refactor", "impact of changing", "safe to rename"
- "analyze dependencies", "call hierarchy", "incoming calls"
- "check this code", "verify implementation", "LSP diagnostics"

## Core Decision Tree

```
WHAT DO YOU NEED?
│
├─ Symbol definition or implementation
│  └─ USE LSP: goToDefinition, goToImplementation
│
├─ All usages of a symbol
│  └─ USE LSP: findReferences
│
├─ Type info, docs, or signatures
│  └─ USE LSP: hover
│
├─ File structure or symbol list
│  └─ USE LSP: documentSymbol
│
├─ Call graph or dependencies
│  └─ USE LSP: incomingCalls, outgoingCalls
│
├─ Symbol search across workspace
│  └─ USE LSP: workspaceSymbol
│
├─ Literal text search (TODOs, strings, config)
│  └─ USE: Grep (LSP doesn't do text matching)
│
└─ File discovery by pattern
   └─ USE: Glob
```

## The Nine LSP Operations

| Operation              | Purpose                         | Use Before                |
| ---------------------- | ------------------------------- | ------------------------- |
| `goToDefinition`       | Jump to where symbol is defined | Modifying unfamiliar code |
| `findReferences`       | Find all usages of a symbol     | Refactoring, renaming     |
| `goToImplementation`   | Find interface implementations  | Working with polymorphism |
| `hover`                | Get type info, docs, signatures | Understanding APIs        |
| `documentSymbol`       | List all symbols in a file      | Understanding large files |
| `workspaceSymbol`      | Search symbols across codebase  | Finding related code      |
| `prepareCallHierarchy` | Get call hierarchy info         | Analyzing call graphs     |
| `incomingCalls`        | Find callers of a function      | Impact analysis           |
| `outgoingCalls`        | Find functions called by target | Dependency tracing        |

**Required parameters for all operations:**

- `filePath` - Absolute path to file
- `line` - Line number (1-based)
- `character` - Column position (1-based)

**Full operation guide:** [references/lsp-operations-guide.md](./references/lsp-operations-guide.md)

## Pre-Edit Protocol (Mandatory)

Before modifying ANY unfamiliar code:

```
1. NAVIGATE: LSP goToDefinition → understand implementation
2. ANALYZE: LSP findReferences → assess change impact
3. INSPECT: LSP hover → verify type signatures
4. THEN: Make changes
```

**Pre-Edit Checklist:**

- [ ] Used goToDefinition to understand implementation
- [ ] Used findReferences to identify all usages
- [ ] Reviewed type signatures via hover
- [ ] Understand interface/trait contracts
- [ ] Know what breaks if this changes

**Skip any step = incomplete understanding = bugs**

## Post-Edit Verification (Mandatory)

After code changes:

```
1. CHECK: LSP diagnostics for errors/warnings
2. VERIFY: No new type errors introduced
3. CONFIRM: Imports resolve correctly
4. VALIDATE: Interface contracts still satisfied
```

Do NOT claim code works without LSP diagnostics verification.

## LSP Availability Check

Before LSP operations, verify setup:

```bash
# Environment variable must be set
echo $ENABLE_LSP_TOOL  # Should output "1"

# If not set, add to shell profile:
export ENABLE_LSP_TOOL=1
```

**If LSP unavailable:**

1. **Warn user:** "LSP not available. Semantic operations will be less accurate."
2. **Suggest fix:** "Set `ENABLE_LSP_TOOL=1` in your shell profile"
3. **Fall back:** Use Grep/Read with documented limitation
4. **Note limitation:** "Used grep fallback - may include false positives"

**Full setup guide:** [references/lsp-setup-verification.md](./references/lsp-setup-verification.md)

## Server Installation

If LSP servers are not installed, use `/lsp-tools:lsp-setup` for guided installation.

**Quick verification:**

```bash
# Run verification script
bash "${CLAUDE_PLUGIN_DIR}/scripts/bash/verify-lsp-servers.sh"
```

**Per-language installation scripts are available:**

| Language      | Server                 | Install Script                                                                     |
| ------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| TypeScript/JS | vtsls                  | [scripts/bash/install-typescript-lsp.sh](./scripts/bash/install-typescript-lsp.sh) |
| Python        | pyright                | [scripts/bash/install-python-lsp.sh](./scripts/bash/install-python-lsp.sh)         |
| Rust          | rust-analyzer          | [scripts/bash/install-rust-lsp.sh](./scripts/bash/install-rust-lsp.sh)             |
| Go            | gopls                  | [scripts/bash/install-go-lsp.sh](./scripts/bash/install-go-lsp.sh)                 |
| Java          | jdtls                  | [scripts/bash/install-java-lsp.sh](./scripts/bash/install-java-lsp.sh)             |
| Kotlin        | kotlin-language-server | [scripts/bash/install-kotlin-lsp.sh](./scripts/bash/install-kotlin-lsp.sh)         |
| C/C++         | clangd                 | [scripts/bash/install-cpp-lsp.sh](./scripts/bash/install-cpp-lsp.sh)               |
| C#            | OmniSharp              | [scripts/bash/install-csharp-lsp.sh](./scripts/bash/install-csharp-lsp.sh)         |
| PHP           | phpactor               | [scripts/bash/install-php-lsp.sh](./scripts/bash/install-php-lsp.sh)               |
| Ruby          | ruby-lsp               | [scripts/bash/install-ruby-lsp.sh](./scripts/bash/install-ruby-lsp.sh)             |
| HTML/CSS      | vscode-langservers     | [scripts/bash/install-html-css-lsp.sh](./scripts/bash/install-html-css-lsp.sh)     |
| LaTeX         | texlab                 | [scripts/bash/install-latex-lsp.sh](./scripts/bash/install-latex-lsp.sh)           |

**Windows users:** Use corresponding PowerShell scripts in `scripts/powershell/`.

**Server registry with full details:** [references/lsp-server-registry.md](./references/lsp-server-registry.md)

## Why LSP Over Grep

| Metric                     | LSP                         | Grep                               |
| -------------------------- | --------------------------- | ---------------------------------- |
| **Speed (large codebase)** | ~50ms                       | 45+ seconds                        |
| **Accuracy**               | Exact semantic matches      | Text patterns (false positives)    |
| **Token usage**            | ~500 tokens (worth it)      | Burns tokens on irrelevant matches |
| **Type resolution**        | Follows aliases, re-exports | Text only                          |
| **Scope awareness**        | Understands variable scope  | Matches all text                   |

**Example:**

```
Grep "getUserById" → 500+ matches (comments, strings, similar names)
LSP findReferences → 23 matches (exact function usages only)
```

## Red Flags - STOP and Use LSP

If you catch yourself:

- "I'll just grep for the function name"
- "Quick refactor, don't need to check references"
- "Code looks fine, probably works"
- "I know what this function does" (without reading it)
- Proposing changes to unfamiliar code without navigation
- Claiming refactor is complete without impact analysis

**ALL of these mean: STOP. Use LSP first.**

## Token Optimization Awareness

**LSP is more expensive per-call but cheaper overall:**

| Scenario                               | Grep Cost                      | LSP Cost                   |
| -------------------------------------- | ------------------------------ | -------------------------- |
| Find meth