  <note>Literal match for exact short strings</note>
  replace_content relative_path="config.nix" needle="oldValue = true" repl="oldValue = false" mode="literal"
</example>

  <step order="2">
    <action>Step 2: Activate project</action>
  </step>
  activate_project project="project-name"

  <step order="3">
    <action>Step 3: Verify onboarding</action>
  </step>
  check_onboarding_performed

  <step order="4">
    <action>Step 4: If not onboarded, run onboarding</action>
  </step>
  onboarding (if needed)

  <step order="5">
    <action>Step 5: Check available memories</action>
  </step>
  list_memories
</example>

  <step order="2">
    <action>Step 2: Explore class members</action>
  </step>
  get_symbols_overview relative_path="src/main.ts" depth=1

  <step order="3">
    <action>Step 3: Get specific implementation</action>
  </step>
  find_symbol name_path_pattern="MyClass/myMethod" include_body=true
</example>

  <step order="2">
    <action>Step 2: Find all callers</action>
  </step>
  find_referencing_symbols name_path="processData" relative_path="src/processor.ts"

  <step order="3">
    <action>Step 3: Recursively trace for full dependency graph</action>
  </step>
  <note>Repeat steps 1-2 for each caller to build complete dependency tree</note>
</example>

  <step order="2">
    <action>Step 2: Identify all usages</action>
  </step>
  find_referencing_symbols name_path="MyClass/oldMethod" relative_path="src/myclass.ts"

  <step order="3">
    <action>Step 3: Perform the change</action>
  </step>
  replace_symbol_body name_path="MyClass/oldMethod" relative_path="src/myclass.ts" body="..."

  <step order="4">
    <action>Step 4: Update references if interface changed</action>
  </step>
  <note>If method signature changed, update all calling sites identified in step 2</note>
</example>

  <step order="2">
    <action>Step 2: Construct a regex that uniquely targets the lines to replace</action>
  </step>
  <note>Use wildcards to avoid transcribing large sections; DOTALL and MULTILINE are enabled</note>

  <step order="3">
    <action>Step 3: Apply the replacement</action>
  </step>
  replace_content relative_path="src/main.ts" needle="oldPattern.*?boundary" repl="newContent" mode="regex"

  <step order="4">
    <action>Step 4: Verify with diagnostics</action>
  </step>
  get_diagnostics_for_file relative_path="src/main.ts" min_severity=2
</example>

  <note>During implementation</note>
  <note>Follow the patterns loaded from memory</note>

  <note>After implementation</note>
  write_memory "api-client-pattern" "HTTP client pattern using fetch with retry logic..."
</example>

  <note>Skip: After fixing typo in variable name</note>
  <note>No memory needed - not a reusable pattern</note>
</example>

<decision_tree name="serena_code_operation"> What type of code operation is needed? Use get_symbols_overview with depth=0, then depth=1 Use find_symbol with name_path_pattern Use find_symbol with include_body=true Use find_referencing_symbols Use replace_symbol_body Use insert_after_symbol Use insert_before_symbol Use rename_symbol Use find_declaration with a regex capturing the symbol name Use find_implementations Use get_diagnostics_for_file with min_severity=2 Use replace_content with mode="regex" and wildcards Use safe_delete_symbol; inspect returned references if blocked Use Glob for file discovery, Grep for content search; follow up navigation with Serena tools </decision_tree>

<decision_tree name="tool_selection"> What type of operation is needed? Use find_symbol with name_path_pattern Use get_symbols_overview with appropriate depth Use find_referencing_symbols Use replace_symbol_body Use rename_symbol for consistent updates Use insert_before_symbol or insert_after_symbol Use list_memories then read_memory Use write_memory Use edit_memory Use find_declaration with regex Use find_implementations Use get_diagnostics_for_file Use replace_content with regex mode Use safe_delete_symbol Use Glob (find) for files, Grep for content </decision_tree>

<decision_tree name="serena_first_tool_selection"> Tool selection hierarchy: Serena for code intelligence, standard tools for filesystem navigation What type of operation is needed? Use Glob (find with name pattern) Serena no longer provides filesystem navigation tools; Glob is the correct tool for file discovery Use Grep for discovery Use Serena find_symbol or find_referencing_symbols for navigation after identifying location Use Bash ls Use Serena get_symbols_overview (depth=0 first, then depth=1) Use Grep for pattern discovery first, then Read for full context Use Serena find_symbol with name_path_pattern Use find_symbol with substring_matching=true Use Grep Use Serena find_declaration with regex capturing the symbol Use Serena find_implementations Use Serena get_symbols_overview then find_symbol with include_body=true Use Read Use Serena find_referencing_symbols Use Grep with symbol name pattern Use Serena replace_symbol_body Use Serena replace_content with mode="regex" and wildcards Use Serena get_diagnostics_for_file with min_severity=2 Use Serena safe_delete_symbol; inspect returned references if deletion is blocked <unavailable_conditions> Serena project not activated (call initial_instructions then activate_project first) File type not supported by LSP (use Grep or Read) Target file's language is not among the project's active languages — multi-language detection fixed on the dominant language; use Grep plus text edits (see symbol_tools_unavailable_fallback) Tool explicitly fails with error </unavailable_conditions> </decision_tree>

<decision_tree name="language_specific_symbol_operations"> Language-specific guidance for symbol operations Strongly prefer symbol operations (find_symbol, get_symbols_overview) LSP provides accurate symbol resolution Use symbol operations with substring_matching=true Dynamic nature may require broader matching Use Grep for pattern discovery, then Read for full context when structure is complex Use Grep or Read Symbol operations less useful for prose </decision_tree>

<best_practices> Always activate project and check onboarding at session start (SERENA-B001) Always check memories with list_memories and read_memory before implementing new features (SERENA-B002) Use symbol operations (get_symbols_overview, find_symbol) over reading entire files (SERENA-B007) Use Serena symbol tools for code intelligence; use Glob/Grep/ls for filesystem navigation (SERENA-P004) Restrict searches by relative_path when scope is known to improve performance Use substring_matching for uncertain symbol names to broaden search results Record significant patterns with write_memory after discovery (SERENA-B005) Verify freshness of memories read this task via memory_staleness_verification; bump last-verified, correct, or archive as needed (SERENA-B009) Use edit_memory for updating existing memories instead of delete and recreate Follow serena_first_tool_selection decision tree for consistent tool choices Verify symbol changes with find_referencing_symbols before refactoring Follow memory_reading_by_task_type to prioritize relevant memories When a multi-language repo's language detection excludes the target file's language, fall back to Grep plus text edits instead of retrying symbol tools (symbol_tools_unavailable_fallback) </best_practices>

<anti_patterns> Reading entire files when only specific symbols are needed Use get_symbols_overview for file structure and find_symbol with include_body for specific implementations

</anti_patterns>

<error_escalation inherits="core-patterns#error_escalation"> Symbol not found with exact match Memory file not found Conflicting information in memories Memory corruption or invalid state </error_escalation>

<related_skills> Investigation methodology using Serena tools Shared patterns for error escalation, decision criteria, enforcement Nix patterns stored in Serena memories TypeScript patterns stored in Serena memories Go patterns stored in Serena memories Rust patterns stored in Serena memories Common Lisp patterns stored in Serena memories Emacs patterns stored in Serena memories </related_skills>

<related_agents> Complement Serena symbol search with file-level exploration Apply Serena-retrieved context to implementation tasks </related_agents>

Serena Usage