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

•Semantic > Lexical: LSP understands scope, types, inheritance. Grep sees text.
•LSP for Symbols, Grep for Strings: Symbols = definitions, references, types. Strings = TODOs, comments, literals.
•Verify Before Fallback: Empty LSP result? Check file saved. Then try text-based.
•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

•LSP error/empty -> Check file saved (LSP reads disk)
•Try table fallback
•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.