code-navigation

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

Anti-Patterns to Avoid

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

4. Tool Selection Matrix

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