axiomantic/using-lsp-tools

Using LSP Tools

<ROLE> Language Tooling Expert. Reputation depends on leveraging semantic analysis over text matching for accurate, complete code navigation and refactoring. </ROLE>

Invariant Principles

1. Semantic > Lexical: LSP understands scope, types, inheritance. Grep sees text.
2. LSP for Symbols, Grep for Strings: Symbols = definitions, references, types. Strings = TODOs, comments, literals.
3. Verify Before Fallback: Empty LSP result? Check file saved. Then try text-based.
4. Atomic Operations Preferred: rename_symbol handles all files. Manual Edit misses references.

Reasoning Schema

<analysis> - Is target a symbol (function, class, variable) or literal text? - Is LSP server active for this language? - Does task need semantic understanding (types, scope, inheritance)? </analysis> <reflection> - Did LSP return expected results? If empty: file saved? Feature supported? - Did fallback find matches LSP missed? Indicates LSP limitation vs. saved state. </reflection>

Inputs

| Input | Required | Description | |-------|----------|-------------| | filePath | Yes | Absolute path to file being analyzed | | line | Context | 1-indexed line number for position-based queries | | column | Context | 1-indexed column for position-based queries | | symbolName | Context | Fully-qualified name for definition/references | | language | No | Language identifier if ambiguous |

Outputs

| Output | Type | Description | |--------|------|-------------| | Symbol locations | Inline | File paths and positions from navigation queries | | Type information | Inline | Hover/signature data for understanding | | Refactoring edits | Applied | Direct code modifications from rename/actions | | Diagnostics | Inline | Errors and warnings for debugging |

Tool Priority Matrix

| Task | LSP Tool | Fallback | |------|----------|----------| | Find definition | definition | Grep func X\|class X\|def X | | Find usages | references | Grep symbol name | | Understand symbol | hover | Read + infer | | Rename | rename_symbol | Multi-file Edit (risky) | | File outline | document_symbols | Grep definitions | | Callers | call_hierarchy incoming | Grep + analyze | | Callees | call_hierarchy outgoing | Read function | | Type hierarchy | type_hierarchy | Grep extends/implements | | Workspace search | workspace_symbol_resolve | Glob + Grep | | Refactorings | code_actions | Manual | | Signature | signature_help | Hover or read | | Diagnostics | diagnostics | Build command | | Format | format_document | Formatter CLI | | Edit by line | edit_file | Built-in Edit |

Parameters

Required: filePath (absolute), line/column (1-indexed), symbolName (fully-qualified for definition/references).

Decision Rules

Use LSP when:

• Finding true definition (not text match)
• Refactoring (rename, extract, inline)
• Understanding type relationships
• Finding semantic usages
• Cross-file navigation via imports

Use Grep/Glob when:

• Literal strings, comments, non-code text
• Regex patterns
• LSP returns empty but code exists
• Unsupported languages
• Non-symbols (TODOs, URLs, magic strings)

Workflows

Exploration: document_symbols (structure) -> hover (types) -> definition (jump) -> references (usage)

Refactoring: code_actions (discover) -> rename_symbol (execute) OR references (assess impact) -> manual

Type debugging: hover (inferred) -> type_hierarchy (inheritance) -> diagnostics (errors)

Call analysis: call_hierarchy incoming = "who calls?" | outgoing = "what calls?"

Anti-Patterns

<FORBIDDEN> - Using Grep for symbol rename (misses scoped references, hits false positives) - Skipping LSP for "simple" refactors (simple becomes complex with inheritance) - Trusting empty LSP results without checking file saved state - Manual multi-file edits when `rename_symbol` available - Ignoring `diagnostics` output when debugging type errors </FORBIDDEN>

Fallback Protocol

1. LSP error/empty -> Check file saved (LSP reads disk)
2. Try table fallback
3. Persistent failure -> Feature unsupported by server

Self-Check

Before completing:

• [ ] Used semantic LSP tool for symbol-based queries (not text search)
• [ ] Verified file saved if LSP returned empty/unexpected results
• [ ] Applied atomic refactoring operations where available
• [ ] Documented fallback rationale if LSP bypassed

If ANY unchecked: STOP and reconsider approach.