Pathfinder

Pathfinder Skill

Session Bootstrap

Before any code exploration or analysis, confirm Pathfinder is available:

mcp({ server: "pathfinder" })

• Tools listed → Pathfinder is live. Use semantic tools for all source code operations.
• Error or empty → Pathfinder unavailable. Use built-in tools. Stop here.

Check once per session. Re-check only if a tool call fails with a connection error.

Semantic Paths

All Pathfinder tools that take a semantic_path require file_path::symbol_chain:

• ✅ src/auth.ts::AuthService.login
• ✅ crates/pathfinder/src/server.rs::PathfinderServer.new
• ❌ AuthService.login (interpreted as a file named "AuthService.login")
• ❌ login (interpreted as a file named "login")

Bare file paths (no ::) are valid only for whole-file operations like read_source_file.

Workflows

Explore (Understand a Codebase)

1. get_repo_map(path=".", depth=5, visibility="public")
   → Full project skeleton with semantic paths
   → Low coverage_percent? Increase max_tokens
   → Files show [TRUNCATED]? Increase max_tokens_per_file
   → Use changed_since="3h" to scope to recent changes
   → Use include_extensions=["ts","tsx"] for language focus
   → Use include_tests=false to exclude test symbols

2. search_codebase(query="<entry point>", path_glob="src/**/*")
   → Find main handlers, routes, or CLI commands
   → Copy enclosing_semantic_path for next step
   → Check files_searched/files_in_scope/coverage_percent for completeness

3. read_with_deep_context(semantic_path="<entry point>")
   → Source + signatures of everything it calls
   → First call may take 5-30s during LSP warmup

4. find_callers_callees(semantic_path="<key function>", max_depth=3)
   → Who calls it (incoming) + what it calls (outgoing)

Done when: You can explain the architecture and trace a request through the system.

Impact Assessment (Before Any Change)

1. read_with_deep_context(semantic_path="<target>")
   → Current code + dependency signatures

2. find_callers_callees(semantic_path="<target>", max_depth=3)
   → All callers = blast radius
   → For large API changes: use max_depth=4-5
   → When NOT degraded: empty arrays = LSP confirmed zero

3. For each caller:
   read_symbol_scope(semantic_path="<caller>")
   → Verify assumptions about the target's interface

4. get_definition(semantic_path="<suspicious dependency>")
   → Jump to external dependency source

Rule: ALWAYS run find_callers_callees before recommending a refactor.

Audit (Review Code Quality)

1. get_repo_map(path=".", depth=5, visibility="all")

2. For each module:
   a. read_source_file(filepath="<file>", detail_level="source_only")
      → For targeted line reading (lowest tokens)
   b. read_source_file(filepath="<file>", detail_level="compact")
      → For code + flat symbol list
   c. read_with_deep_context(semantic_path="<complex function>")
   d. search_codebase(query="<danger pattern>", is_regex=true)
      Go: panic|log\.Fatal
      Rust: unwrap\(\)|expect\(|panic!
      Python: except:|pass\s+# noqa
      TypeScript: as any|@ts-ignore
   e. search_codebase(query="TODO|FIXME|HACK", filter_mode="comments_only")

3. For critical findings:
   find_callers_callees(semantic_path="<problem>")
   → Blast radius before recommending changes

Debug (Trace a Problem)

1. read_with_deep_context(semantic_path="<failing function>")
   → Source + all dependencies

2. get_definition(semantic_path="<suspicious call>")
   → Jump to the callee's definition

3. find_callers_callees(semantic_path="<failing function>", max_depth=1)
   → Find callers to understand inputs

4. search_codebase(query="<error message>")
   → Locate error origin

Search Optimization

search_codebase parameters for token efficiency:

Coverage metadata:

• files_searched — actual files that were searched
• files_in_scope — files matching path_glob
• coverage_percent — % of in-scope files searched. <100% means some files skipped.

Search counts:

• total_matches — post-filter count (equals matches.len()). This is the ground truth.
• raw_match_count — ripgrep pre-filter count (before filter_mode drops comments/strings).
• filtered_count — raw_match_count - total_matches (how many rows were removed by the filter).
• truncated — result set was capped at max_results. Increase max_results or narrow your query.

Token-saving pattern:

search_codebase(query="deprecated_api",
                known_files=["src/fileA.ts", "src/fileB.ts"],
                exclude_glob="**/*.test.*",
                group_by_file=true)

Token Budget Controls

Use these parameters to prevent context-window overflow in large repos:

find_callers_callees budget parameters

When references_truncated: true in the response, the budget was hit — either increase max_references or decrease max_depth.

read_with_deep_context budget parameters

When dependencies_truncated: true in the response, increase max_dependencies to see more.

get_repo_map budget parameters

Check max_tokens_used in the response to see the effective budget applied.

LSP Degraded Mode

Tools that use LSP: get_definition, find_callers_callees, read_with_deep_context, find_all_references.

Visual indicator: When degraded, text output starts with:

⚠️ DEGRADED ({reason}) — {tool-specific guidance}

Every response includes degraded (bool), degraded_reason, and lsp_readiness:

LSP Readiness values:

• "ready" — LSP is fully operational
• "warming_up" — LSP still indexing
• "unavailable" — No LSP available

Critical rule: When degraded: true, never treat empty results as confirmed-zero. Re-run after LSP finishes indexing, or check lsp_health.

Null vs Empty Array distinction:

• incoming: null (or outgoing: null, references: null) — unknown, degraded
• incoming: [] (or outgoing: [], references: []) — LSP confirmed: truly zero

Error Recovery

SYMBOL_NOT_FOUND with did_you_mean suggestions:

Error: SYMBOL_NOT_FOUND for "src/auth.ts::AuthServce.login"
       data.details.did_you_mean: ["AuthService.login", "AuthService.logout"]
→ Use the corrected path from did_you_mean
→ If suggestions list is empty: use search_codebase(query="login") to find the right file

SYMBOL_NOT_FOUND — no suggestions (wrong file):

Error: SYMBOL_NOT_FOUND, did_you_mean: []
→ The symbol probably lives in a different file
→ search_codebase(query="<symbol_name>") → find file → retry with correct path

LSP Timeout / Degraded Navigation:

degraded=true, degraded_reason="lsp_warmup_empty_unverified"
→ Check lsp_health for indexing status
→ Re-run after indexing completes
→ If no_lsp: use search_codebase + read_symbol_scope as fallback

Common Mistakes

Wrong File in Semantic Path

If get_definition("logic.go::CompleteLesson") returns SYMBOL_NOT_FOUND, the symbol might be defined in a different file. The semantic path requires the actual file where the symbol is defined, not just any file in the module.

Solution:

1. Use search_codebase(query="CompleteLesson") to find which file defines the symbol
2. Use read_source_file(filepath="logic.go", detail_level="symbols") to see all symbols in a specific file
3. Then use the correct file path in the semantic path

Tool Selection: read_file vs read_source_file

read_source_file detail_level options

Quick Reference

Fallback (Pathfinder Unavailable)

If tools are not available, fall back transparently:

Do not block on Pathfinder. Complete the work with built-in tools.