Codebase Retrieval

When the user asks about their codebase, use the OpenACE tools (semantic_search, find_symbol, get_file_outline) to find relevant code instead of guessing or asking the user to provide file paths.

When to Use This Skill

Activate this skill when the user:

• Asks where something is implemented ("Where is user authentication handled?")
• Needs to find code locations ("Find the database connection code")
• Wants to understand how something works ("How does the payment processing work?")
• Needs to make changes and doesn't know where ("I need to add a new API endpoint")
• Asks about code structure ("What tests exist for the login feature?")
• Mentions specific concepts that need to be located in the codebase

How to Use Codebase Retrieval

Step 1: Formulate Effective Queries

Create search queries based on the user's request:

• Direct queries: Use function names, class names, or variable names if mentioned
• Conceptual queries: Describe what the code does ("user authentication", "database connection")
• Related patterns: Search for similar functionality or related concepts

Step 2: Choose the Right Tool

Select the tool that best matches the user's request:

• find_symbol: Use when the user mentions a specific name -- a class, function, variable, or type. This performs an exact name lookup and returns the symbol's file path, line range, and signature.
• semantic_search: Use when the user describes a concept or behavior rather than a specific name. This searches by natural language and returns ranked results with relevance scores, file paths, line ranges, and related symbols.
• get_file_outline: Use when the user wants to understand what a particular file contains or needs an overview of a file's structure. This returns all symbols in the file with their kinds, names, line ranges, and signatures.

Step 3: Search the Codebase

Call the chosen tool with the appropriate input:

semantic_search -- pass a natural language description of the code you're looking for:

• "Where is the function that handles user authentication?"
• "What tests are there for the login functionality?"
• "How is the database connected to the application?"
• "Where are API endpoints defined for user management?"

find_symbol -- pass the exact name of the symbol:

• "AuthService"
• "handleLogin"
• "DatabasePool"
• "UserController"

get_file_outline -- pass the relative file path:

• "src/auth/service.ts"
• "lib/database/pool.rs"

Step 4: Analyze and Iterate

From the retrieval results:

• Review the returned code snippets for relevance
• If results aren't helpful, try alternative queries with different terminology
• Search for related concepts if the direct search doesn't yield results
• Combine tools when needed: use semantic_search to locate a file, then get_file_outline to understand its structure, then find_symbol for specific definitions

Step 5: Present Findings

Provide clear, actionable information:

• List relevant files with their paths
• Explain what each file/function does
• Point to specific functions, classes, and line ranges when possible
• Suggest which code should be modified for the requested change

Guidelines

• Be thorough: Search using multiple related queries if the first doesn't yield complete results
• Be specific: Pass detailed queries for better retrieval results
• Stay current: The retrieval tools reflect the current state of the codebase on disk
• Avoid guessing: Always search before making assumptions about code locations
• Iterate: If initial results aren't helpful, reformulate your query and try again