LSP Code Analysis

Abstract

This document specifies the operational requirements and best practices for the lsp-code-analysis skill. It provides a semantic interface to codebase navigation and analysis via the Language Server Protocol (LSP).

[!IMPORTANT] Update Required: You MUST run the installation script to check for updates before using this skill:

bash <(curl -sSL https://raw.githubusercontent.com/lsp-client/lsp-skill/main/scripts/install.sh) <absolute_path_to_this_skill_directory>

Replace <absolute_path_to_this_skill_directory> with the absolute path to the directory containing this SKILL.md file.

Overview

You SHOULD use the lsp CLI tool for semantic code navigation and analysis, and it SHOULD be preferred over read or grep for most code understanding tasks.

• Semantic navigation: Jump to definitions, find references, locate implementations - understands code structure, not just text patterns.
• Language-aware: Distinguishes between variables, functions, classes, types - eliminates false positives from text search.
• Cross-file intelligence: Trace dependencies, refactor safely across entire codebase - knows what imports what.
• Type-aware: Get precise type information, signatures, documentation - without reading implementation code.

Tool Selection

Guideline: Agents SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use read or grep ONLY when semantic analysis is not applicable (e.g., searching for comments or literal strings).

Commands

All commands support -h or --help.

Locating Symbols

Most commands use a unified Locate String syntax via the -L or --locate option.

Syntax: <file_path>[:<scope>][@<find>]

Scope Formats:

• <line>: Single line number (e.g., 42).
• <start>,<end>: Line range with comma (e.g., 10,20).
• <start>-<end>: Line range with dash (e.g., 10-20).
• <symbol_path>: Symbol path with dots (e.g., MyClass.my_method).

Find Pattern (@<find>):

The optional @<find> suffix narrows the target to a text pattern within the selected scope:

• The scope is determined by <scope> (line/range/symbol). If no <scope> is given, the entire file is the scope.
• <find> is matched in a whitespace-insensitive way: differences in spaces, tabs, and newlines are ignored.
• You MAY include the cursor marker <|> inside <find> to specify the exact position of interest within the match (for example, on a variable name, keyword, or operator).
• If <find> is omitted, the command uses the start of the scope (or a tool-specific default) as the navigation target.

Cursor Marker (<|>):

The <|> marker indicates the exact position for symbol resolution. Use it within the find pattern to point to a specific element (e.g., user.<|>name to target the name property).

Examples:

• foo.py@self.<|> - Find self. in entire file, position at cursor marker
• foo.py:42@return <|>result - Find return result on line 42, position at cursor marker
• foo.py:10,20@if <|>condition - Find if condition in lines 10-20, position at cursor marker
• foo.py:MyClass.my_method@self.<|> - Find self. within MyClass.my_method, position at cursor marker
• foo.py:MyClass - Target the MyClass symbol directly

Agents MAY use lsp locate <string> with the -c or --check flag to verify if the target exists in the file and view its context before running other commands.

# Verify location exists
lsp locate "main.py:42@process_data" --check

Outline: File Structure

The outline command SHOULD be used before reading files to obtain a structural overview, and it SHOULD be preferred over a full read for non-essential code.

# Main symbols (classes, functions, methods)
lsp outline <file_path>

# All symbols (includes variables, parameters)
lsp outline <file_path> --all

Definition: Navigate to Source

The definition command is RECOMMENDED for verifying function signatures without reading the full implementation.

# By locate string
lsp definition -L "models.py:User.get_id"

# Declaration instead of definition
lsp definition -L "models.py:25" --decl

# Type definition
lsp definition -L "models.py:30" --type

Reference: Find All Usages

The reference command is REQUIRED before refactoring or deleting code. Agents SHOULD use --impl for finding implementations in abstract codebases.

# Find references
lsp reference -L "main.py:MyClass.run@logger"

# Find implementations
lsp reference -L "api.py@IDataProvider" --impl

# More context lines
lsp reference -L "app.py:10@TestClass" --context-lines 5

# Limit results and use pagination
lsp reference -L "utils.py:helper" --max-items 50 --start-index 0

Hover: Get Documentation

The hover command SHOULD be preferred over read for understanding API contracts. It returns docstrings and type signatures.

# By line
lsp hover -L "main.py:42"

# By text search
lsp hover -L "models.py@process_data<|>"

Search: Global Symbol Search

The search command is RECOMMENDED when the symbol location is unknown. Agents SHOULD use --kind to filter results.

# Search symbols (defaults to current directory)
lsp search "MyClassName"

# Specific workspace
lsp search "UserModel" --workspace /path/to/project

# Filter by kind (can be specified multiple times)
lsp search "init" --kind function --kind method

# Limit results
lsp search "Config" --max-items 10

# Pagination
lsp search "User" --max-items 20 --start-index 0

Rename: Safe Refactoring

The rename command facilitates workspace-wide symbol renaming. A two-step workflow MUST be followed: preview then execute.

# Step 1: Preview changes and get rename_id
lsp rename preview new_name -L "models.py:OldName"

# Step 2: Execute changes using the rename_id from preview
lsp rename execute <rename_id>

# Execute with exclusions
lsp rename execute <rename_id> --exclude tests/test_old.py --exclude legacy/

Symbol: Local Symbol Info

The symbol command MAY be used to anchor subsequent hover or definition calls by providing precise coordinate information.

# By line
lsp symbol -L "main.py:15"

# By text search
lsp symbol -L "utils.py@UserClass<|>"

Server: Manage Background Servers

The background manager starts automatically. Manual control is OPTIONAL.

# List running servers (default)
lsp server
lsp server list

# Start server for a project
lsp server start <path>

# Stop server for a project
lsp server stop <path>

Best Practices

General Workflows

Understanding Unfamiliar Code

The RECOMMENDED sequence for exploring new codebases:

# Step 1: Start with outline - Get file structure without reading implementation
lsp outline <file_path>

# Step 2: Inspect signatures - Use hover to understand API contracts
lsp hover -L "<file_path>:<symbol_name>"

# Step 3: Navigate dependencies - Follow definition chains
lsp definition -L "<file_path>:<symbol_name>"

# Step 4: Map usage - Find where code is called with reference
lsp reference -L "<file_path>:<symbol_name>"

Refactoring Preparation

The REQUIRED steps before modifying code:

# Step 1: Find all references - Identify impact scope
lsp reference -L "<file_path>:<symbol_name>"

# Step 2: Check implementations - For interfaces/abstract classes using --impl
lsp reference -L "<file_path>:<interface_name>" --impl

# Step 3: Verify type definitions - Understand type propagation with --type
lsp definition -L "<file_path>:<symbol_name>" --type

# Step 4: Preview Rename - See workspace-wide impact before executing
lsp rename preview <new_name> -L "<file_path>:<symbol_name>"

Debugging Unknown Behavior

# Step 1: Locate symbol definition workspace-wide
lsp search "<symbol_name>"

# Step 2: Verify implementation details
lsp definition -L "<file_path>:<symbol_name>"

# Step 3: Trace all callers to understand invocation context
lsp reference -L "<file_path>:<symbol_name>"

Finding Interface Implementations

# Step 1: Locate interface definition
lsp search "IUserService" --kind interface

# Step 2: Find all implementations
lsp reference -L "src/interfaces.py:IUserService" --impl

Tracing Data Flow

# Step 1: Find where data is created
lsp search "UserDTO" --kind class

# Step 2: Find where it's used
lsp reference -L "models.py:UserDTO"

# Step 3: Check transformations
lsp hover -L "transform.py:map_to_dto"

Understanding Type Hierarchies

# Step 1: Get class outline
lsp outline models.py

# Step 2: Find subclasses (references to base)
lsp reference -L "models.py:BaseModel"

# Step 3: Check type definitions
lsp definition -L "models.py:BaseModel" --type

Performance Tips

• Use outline aggressively - Avoid reading entire files when possible.
• Leverage symbol paths - More precise than line numbers for nested structures.
• Use --max-items - Limit results in large codebases.
• Prefer hover over definition - For understanding without navigating.
• Verify with locate - If a command fails, use lsp locate to debug the target.

Domain-Specific Guides

For specialized scenarios, see:

• Frontend: bp_frontend.md
• Backend: bp_backend.md