Pathfinder Workflow

Pathfinder Workflow Skill

Purpose

Provides task-specific tool chains that leverage Pathfinder's semantic tools for maximum effectiveness. Each workflow is a concrete sequence of tool calls optimized for a specific goal.

When to Invoke

• Starting work on an unfamiliar codebase → use Explore workflow
• Refactoring a function or class → use Refactor workflow
• Implementing a new feature → use Implement workflow
• Auditing code quality → use Audit workflow
• Debugging a failing function → use Debug workflow

Foundation: Why Pathfinder?

Pathfinder tools operate at the semantic level (symbols, functions, classes) while built-in tools operate at the text level (lines, strings, files). Semantic tools give you:

• Precise targeting — address a function by name, not by line number
• Auto-indentation — edits match surrounding code style
• LSP validation — edits are checked for errors before writing to disk
• Optimistic Concurrency Control (OCC) — version hashes prevent overwriting concurrent changes

What is a Semantic Path?

A Semantic Path is the unified addressing scheme for Pathfinder tools. IMPORTANT: Unless targeting an entire file (like BOF/EOF insertions), semantic paths MUST ALWAYS include the file path + :: + the symbol chain. Providing just the symbol name (e.g. send or login) will FAIL because Pathfinder will mistakenly interpret it as a bare file named send.

Correct Semantic Paths:

• src/auth.ts::AuthService.login
• crates/pathfinder-lsp/src/client/process.rs::send Incorrect Semantic Paths:
• AuthService.login
• send Bare File (only for BOF/EOF insertions, config tools):
• src/auth.ts

Tool Preference Table

Canonical source: The always-on rule pathfinder-tool-routing.md is the single source of truth for which tool to use. This table adds the "Why" column for deeper understanding but defers to the rule for routing decisions.

Keep Using Built-in Tools For

These tasks have no Pathfinder equivalent — always use built-in tools:

• Listing directory contents → Bash (with ls) or Glob
• Running commands (tests, linters, builds) → Bash
• Viewing binary files (images, videos) → Read
• Quick one-line fixes where you already know the exact text → Edit is fine for trivial edits

OCC (Optimistic Concurrency Control)

All Pathfinder edit tools require a base_version (SHA-256 hash). This prevents overwriting changes made by other tools or agents.

Where to Get Version Hashes

The Hash Chain Pattern

Edits form a chain — each edit produces a new hash for the next edit:

read_symbol_scope → version_hash (v1)
replace_body(base_version=v1) → new_version_hash (v2)
insert_after(base_version=v2) → new_version_hash (v3)

If you get VERSION_MISMATCH: Re-read the symbol to get the latest hash, then retry.

Important: validate_only does NOT write to disk, so new_version_hash is null. Reuse your original base_version for the real edit after a successful dry-run.

Validation Overrides

Every edit tool supports ignore_validation_failures (default: false). When set to true, the edit is written to disk even if LSP validation detects introduced errors.

When to use ignore_validation_failures: true:

• LSP is flaky or unavailable for the target language (check validation_skipped_reason)
• You are making a deliberate change that temporarily breaks type checking (e.g., updating an interface before updating all callers)
• The LSP reports false positives for your specific pattern

When NOT to use it:

• For normal edits where LSP is healthy — let validation catch genuine errors
• As a blanket habit — always try the edit with validation first

Workflow 1: Explore (Understand a Codebase)

Goal: Build a mental model of the project from zero context.

Step 1: get_repo_map(path=".", depth=5, visibility="public")
        → Get the full project skeleton with semantic paths
        → Note the tech_stack and files_scanned to understand project scale
        → If coverage_percent is low: increase max_tokens (more files)
        → If files show [TRUNCATED DUE TO SIZE]: increase max_tokens_per_file (more detail per file)
        → Use visibility="all" to include private symbols (better for auditing)
        → Use include_imports="third_party" (default) to see external dependencies,
          or "all" to see internal imports too, or "none" for a minimal skeleton
        → Use changed_since="3h" (or a git ref like "HEAD~5") to scope the map
          to only recently modified files — useful when reviewing a PR or
          picking up where a previous session left off.
        → Use include_extensions=["ts","tsx"] to focus on a specific language
          in mixed-language repos. Mutually exclusive with exclude_extensions.

Step 2: search_codebase(query="<entry point pattern>", path_glob="src/**/*")
        → Find main entry points, API handlers, or CLI commands
        → Use enclosing_semantic_path from results for next step

Step 3: read_with_deep_context(semantic_path="<chosen entry point>")
        → Read the entry point + all functions it calls
        → Follow the dependency chain to understand data flow
        → NOTE: First call may be slow (30–120s) due to LSP warm-up. This is
          expected — subsequent calls are fast. If degraded=true in metadata,
          LSP was unavailable; dependencies will be empty but source is still returned.

        Alternative: read_source_file(filepath="<key file>", detail_level="compact")
        → When you need the full file context + symbol tree, not just one function

Step 4: analyze_impact(semantic_path="<key function>", max_depth=2)
        → Understand who calls this function (incoming)
        → Understand what it depends on (outgoing)

When to stop: You can explain the project's architecture, identify its core modules, and trace a request through the system.

Workflow 2: Refactor (Safely Change Code)

Goal: Modify existing code without breaking callers or dependencies.

Step 1: read_with_deep_context(semantic_path="<target>")
        → Read the target function and everything it calls
        → Save the version_hash for editing

Step 2: analyze_impact(semantic_path="<target>", max_depth=2)
        → Identify ALL callers — these are your blast radius
        → Version hashes are returned for all referenced files

Step 3: validate_only(semantic_path="<target>", edit_type="replace_body",
                      new_code="<your refactored code>", base_version="<hash>")
        → Dry-run the edit to check for LSP errors BEFORE writing

Step 4: replace_body(semantic_path="<target>",
                     new_code="<your refactored code>", base_version="<hash>")
        → Apply the edit with semantic addressing + auto-indentation
        → Check the validation result in the response

Step 5: (If callers need updating) For each caller from Step 2:
        read_symbol_scope → replace_body → verify

Step 6: Bash("cargo test" / "npm test")
        → Verify the refactoring didn't break anything

Key rule: ALWAYS run analyze_impact before refactoring. Agents that skip this step risk breaking unknown callers.

Workflow 3: Implement (Add New Code)

Goal: Add a new function, class, or feature to an existing codebase.

Step 1: get_repo_map(path="<relevant directory>")
        → Understand existing structure and naming patterns
        → Identify the right file to add the new code to

Step 2: read_symbol_scope(semantic_path="<neighboring function>")
        → Read an existing function in the same file for style reference
        → Save the version_hash

Step 3: insert_after(semantic_path="<anchor symbol>",
                     new_code="<your new function>", base_version="<hash>")
        → Add the new code after an appropriate symbol
        → Use bare file path (no "::") to append at EOF

Step 4: (If adding imports) insert_before(semantic_path="<filepath>",
                     new_code="<import statements>", base_version="<new hash>")
        → Use bare file path to insert at the top of the file

Step 5: Bash("cargo test" / "npm test")

Workflow 4: Audit (Review Code Quality)

Goal: Systematically review a codebase for issues.

Step 1: get_repo_map(path=".", depth=5, visibility="all")
        → Get complete project overview including private symbols

Step 2: For each module/feature area:
        a. read_source_file(filepath="<module entry file>", detail_level="compact")
           → Get the full file with its symbol tree for a structural overview
        b. read_symbol_scope(semantic_path="<public API function>")
           → Review the public interface in detail
        c. read_with_deep_context(semantic_path="<complex function>")
           → Check that dependencies are reasonable
        d. search_codebase(query="<language-specific danger pattern>",
                          path_glob="src/**/*", is_regex=true)
           → Find potential crash/error points. Examples by language:
             - 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")
           → Find technical debt markers

Step 3: For critical findings:
        analyze_impact(semantic_path="<problematic function>")
        → Assess blast radius before recommending changes

Workflow 5: Debug (Trace a Problem)

Goal: Understand why a specific function is failing.

Step 1: read_with_deep_context(semantic_path="<failing function>")
        → See the function AND all its dependencies

Step 2: get_definition(semantic_path="<suspicious call within the function>")
        → Jump to the definition of a called function to inspect its contract

Step 3: analyze_impact(semantic_path="<failing function>", max_depth=1)
        → Find all callers to understand what inputs are being passed

Step 4: search_codebase(query="<error message or pattern>")
        → Find where the error originates in the codebase

Advanced Patterns

Multi-File Edit Chain

When a refactor touches multiple files (e.g., update interface + all implementations + tests), maintain the version hash chain per file:

# File A: Update the interface
read_symbol_scope("fileA.go::Storage") → hash_A1
replace_full("fileA.go::Storage", base_version=hash_A1) → hash_A2

# File B: Update implementation (uses its OWN hash, not File A's)
read_symbol_scope("fileB.go::PostgresStorage.Create") → hash_B1
replace_body("fileB.go::PostgresStorage.Create", base_version=hash_B1) → hash_B2

# File C: Update tests
read_symbol_scope("fileC_test.go::TestCreate") → hash_C1
replace_body("fileC_test.go::TestCreate", base_version=hash_C1) → hash_C2

Key insight: Each file has its own independent hash chain. Don't mix hashes across files.

Same-File Multi-Symbol Edit

When editing multiple non-contiguous symbols in the same file (e.g., fixing 3 unrelated functions), use replace_batch:

# Preferred: single atomic call with replace_batch
read_symbol_scope("main.py::_collect_words") → hash_v1
replace_batch(filepath="main.py", base_version=hash_v1, edits=[
  { semantic_path: "main.py::_collect_words", edit_type: "replace_body", new_code: "..." },
  { semantic_path: "main.py::_patch_audio_urls", edit_type: "replace_body", new_code: "..." },
  { semantic_path: "main.py::_generate_tts", edit_type: "replace_full", new_code: "..." },
]) → hash_v2

All five edit_type values for replace_batch Option A:

• replace_body — replace internal logic, keep signature
• replace_full — replace entire declaration (signature + body + decorators + doc comments)
• insert_before — insert new code before the target symbol
• insert_after — insert new code after the target symbol
• delete — delete the target symbol (no new_code needed)

Why replace_batch is preferred:

• Atomic — all edits land in one write with a single OCC guard
• Each edit targets a symbol name, not a fragile text string
• Edits are applied back-to-front (by byte offset) to avoid offset shifting
• LSP validation runs once on the combined result
• If any edit fails, the entire batch is rolled back atomically

Fallback: sequential chaining (when edits depend on each other's results):

read_symbol_scope("main.py::_collect_words") → hash_v1
replace_body("main.py::_collect_words", base_version=hash_v1) → hash_v2
replace_body("main.py::_patch_audio_urls", base_version=hash_v2) → hash_v3

When to fall back to multiple Edit calls:

• Pathfinder tools are unavailable (server offline)
• Edits are inside non-symbol regions (e.g., top-level constants, inline comments)
• Trivial single-line changes across many locations

Vue SFC Text Targeting

Vue Single-File Components have three zones: <script>, <template>, and <style>. The <script> zone is fully AST-aware (TypeScript symbols are extracted and addressable). The <template> and <style> zones have no AST symbols — use replace_batch with Option B (text targeting) for edits there:

# Edit a template element by surrounding text context
read_source_file("src/views/Dashboard.vue") → hash_v1
replace_batch(filepath="src/views/Dashboard.vue", base_version=hash_v1, edits=[

  # Option A — Script zone: semantic targeting works normally
  { semantic_path: "src/views/Dashboard.vue::setup", edit_type: "replace_body",
    new_code: "..." },

  # Option B — Template zone: text targeting required
  { old_text: "<div class=\"card\">", context_line: 42,
    replacement_text: "<div class=\"card elevated\">" },

  # Option B with normalize_whitespace for multi-line HTML
  { old_text: "<Button @click=\"submit\">",
    context_line: 55, normalize_whitespace: true,
    replacement_text: "<Button @click=\"handleSubmit\">" },
])

Rules for text targeting:

• context_line (1-indexed) anchors the search — Pathfinder scans ±10 lines around it
• Set normalize_whitespace: true to collapse \s+ → single space (safe for HTML; do NOT use for Python or YAML where indent is significant)
• Both Option A and Option B edits may be mixed in a single replace_batch call
• If any edit fails (e.g., TEXT_NOT_FOUND), the entire batch is rolled back atomically

Efficient Search

search_codebase has several parameters that significantly reduce token waste:

Token efficiency pattern:

# After reading fileA.ts and fileB.ts, search without re-reading their content:
search_codebase(query="deprecated_api",
                known_files=["src/fileA.ts", "src/fileB.ts"],
                exclude_glob="**/*.test.*",
                group_by_file=true)

Discovery→Edit Chaining

search_codebase and get_repo_map return version hashes, so you can skip the read step and edit directly:

search_codebase(query="deprecated_function") → results with version_hash per file
replace_full(semantic_path=result.enclosing_semantic_path,
             base_version=result.version_hash, new_code="<fixed code>")

Use sparingly — only when the search result gives you enough context to write the replacement code without reading the full function.

Error Recovery Patterns

SYMBOL_NOT_FOUND

Error: SYMBOL_NOT_FOUND for "src/auth.ts::AuthServce.login"
       did_you_mean: ["AuthService.login", "AuthService.logout"]

Recovery:
→ Use the corrected path from did_you_mean
→ Retry: read_symbol_scope(semantic_path="src/auth.ts::AuthService.login")

VERSION_MISMATCH

Error: VERSION_MISMATCH — file was modified since your last read

Recovery:
→ Re-read the file: read_symbol_scope(semantic_path="<target>")
→ Get the fresh version_hash
→ Retry the edit with the new base_version

Validation Failures (introduced_errors)

Response: validation.status = "failed"
          introduced_errors: [{ message: "cannot find name 'foo'", ... }]

Recovery:
→ Read the introduced_errors to understand what broke
→ Fix your new_code to address the errors
→ Use validate_only to dry-run before committing the fix
→ Apply the corrected edit

Validation Skipped

Response: validation.validation_skipped = true
          validation.validation_skipped_reason = "no_lsp" | "lsp_not_on_path" |
              "lsp_start_failed" | "lsp_crash" | "lsp_timeout" |
              "pull_diagnostics_unsupported"

This means: The edit was written to disk but was NOT validated by LSP.

When you see this:
→ Check capabilities.lsp.per_language via get_repo_map to understand LSP status
→ The edit landed successfully — but you have no compile-time safety net
→ Compensate by running tests (Bash) or manual review
→ If the reason is "lsp_not_on_path", suggest the user install the language server
→ If the reason is "lsp_crash" or "lsp_timeout", the LSP may recover on next edit

TEXT_NOT_FOUND (replace_batch Option B)

Error: TEXT_NOT_FOUND for old_text="<div class=\"card\">"

Recovery:
→ The old_text was not found within ±10 lines of context_line
→ Re-read the file with read_source_file to find the correct text and line number
→ Adjust old_text to match exactly, or update context_line
→ Consider normalize_whitespace: true if whitespace differences are the issue
→ Retry the replace_batch call

Tool Chain Quick Reference

Graceful Fallback

If Pathfinder MCP tools are not available (server offline, tools not surfaced in the function list), fall back to built-in tools transparently:

Rules:

• Do not block on Pathfinder being unavailable — complete the work with built-in tools
• Note the degradation to the user if asked
• When Pathfinder comes back online, resume using it immediately — no need to redo prior work