Code Navigation Standards

1. Context

This skill enforces "LSP First" - using the Language Server Protocol (cclsp) for code navigation instead of token-heavy text processing. This implements the "Precision and Parsimony" principle from the Flywheel architecture.

Key Principle: Do not read entire files to find a single definition. Use LSP to navigate like a Software Architect.

2. Verified Procedure

Definition Lookup

# DO: Use LSP to jump directly to definition
cclsp definition <symbol>

# DON'T: Read the entire file searching for the definition
cat src/large_file.py | grep "def function_name"

Finding References

# DO: Use LSP to find all usages
cclsp references <symbol>

# DON'T: Grep across the entire codebase
grep -r "function_name" .

Type and Signature Information

# DO: Use LSP hover to see parameters and types
cclsp hover <symbol>

# DON'T: Read function definition to understand signature
Read src/file.py  # Then manually parse the function signature

Codebase Structure Exploration

# DO: Use Glob for file discovery first, then LSP for details
Glob "**/*.py" | cclsp outline

# DON'T: Read every file to understand structure
for file in $(find . -name "*.py"); do cat $file; done

3. Negative Knowledge

Failed Attempts

| Attempt | Why It Failed | Token Cost | |---------|---------------|------------| | Reading full files to find class definitions | Wasted 10,000+ tokens on a 500-line file when LSP would have returned the answer in <50 tokens | 200x overhead | | Using grep -r across large codebases | Returned too many false positives, required reading multiple files to find the right reference | 50x overhead | | Guessing import paths without LSP verification | Led to incorrect imports that failed at runtime | Required debugging iteration | | Reading documentation files instead of using cclsp hover | Documentation was outdated; LSP provided current signature from source | Incorrect information |

Anti-Patterns to Avoid

Token Waste: Reading entire files when you only need a single function signature.
Grep Overuse: Using grep for semantic queries that LSP can answer precisely.
Path Guessing: Assuming file locations instead of using cclsp definition to verify.
Ignoring Type Information: Not using cclsp hover to understand parameter types and return values.

4. Tool Selection Matrix

| Task | Tool | Rationale | |------|------|-----------| | Find where function is defined | cclsp definition | Direct, token-efficient | | Find all usages of a class | cclsp references | Semantic understanding | | Understand function signature | cclsp hover | Includes types and docs | | Find files matching pattern | Glob | Fast file discovery | | Search for string literal | Grep | Text search, not semantic | | Read implementation details | Read | Only after LSP narrows scope |

5. Workflow Example

Task: "Find where UserAuth class is used and understand its constructor"

# Step 1: Find the definition
cclsp definition UserAuth

# Step 2: Get constructor signature
cclsp hover UserAuth.__init__

# Step 3: Find all references
cclsp references UserAuth

# Step 4: Only NOW read specific files if needed
Read src/auth/user_auth.py

Token Savings: ~90% compared to reading all files that might contain UserAuth.

6. Integration with Flywheel

Before: Agent reads 5-10 files (2000+ lines) to understand a function.
After: Agent uses LSP to get exact definition in <20 lines of output.
Result: Faster responses, lower costs, more context budget for complex reasoning.

7. Verification Checklist

Before opening a file with Read, ask:

[ ] Can cclsp definition answer this question?
[ ] Can cclsp references show me where this is used?
[ ] Can cclsp hover give me the signature/type?
[ ] Have I used Glob to narrow down the file search first?

If any answer is YES, use that tool FIRST.

8. Maintenance Notes

LSP Availability: Requires cclsp.json configuration in repository root.
Language Support: Check which languages are supported by the LSP server in your environment.
Fallback: If LSP fails, THEN use Grep + Read, but document the failure in this skill's Negative Knowledge.

Last Updated: 2025-12-31 Source: The CLAUDE.md Blueprint - LSP First Principle