understand

name	understand
description	Understand a file or symbol's structure and dependencies using code intelligence tools
allowed-tools	["mcp__gitkb__kb_symbols","mcp__gitkb__kb_callers","mcp__gitkb__kb_callees","mcp__gitkb__kb_symbol_refs"]

/understand <file|symbol>

Analyze a file or symbol using code intelligence tools to understand its structure and dependencies.

When to Use

• Before modifying unfamiliar code
• When trying to understand how a module works
• When investigating where functionality lives

Steps

For a File Path

When the argument looks like a file path (e.g., src/services/auth.ts):

1. List symbols in the file:

   kb_symbols with file_path: "src/services/auth.ts"
   

2. For key functions/methods, show their connections:

   kb_callers with symbol: "src/services/auth.ts::login"
   kb_callees with symbol: "src/services/auth.ts::login"
   

3. Check if any documents reference this code:

   kb_symbol_refs with symbol: "src/services/auth.ts::login"
   

For a Symbol Name

When the argument contains :: or looks like a function name:

1. Find the symbol:

   kb_symbols with search: "login"
   

2. Show callers (who calls this):

   kb_callers with symbol: "src/services/auth.ts::login"
   

3. Show callees (what this calls):

   kb_callees with symbol: "src/services/auth.ts::login"
   

4. Find related documents:

   kb_symbol_refs with symbol: "src/services/auth.ts::login"
   

Output Format

Provide a summary with:

1. Symbol Overview: Kind, signature, location
2. Who Calls It: Direct callers (up to 10)
3. What It Calls: Direct callees (up to 10)
4. Related Documents: Any KB docs that reference this code

Example

Input: /understand src/services/auth.ts

Output:

## src/services/auth.ts - Authentication Module

### Symbols (5)
- `login(credentials: Credentials): Promise<Token>` (function)
- `logout(token: Token): Promise<void>` (function)
- `validateToken(token: Token): boolean` (function)
- `AuthConfig` (interface)
- `AuthError` (class)

### Key Function: login()

**Callers (3):**
- src/routes/auth.ts:45 → handleRequest()
- src/routes/auth.ts:89 → handleRefresh()
- src/middleware/auth.ts:22 → authenticate()

**Callees (2):**
- src/db/users.ts::findUser()
- src/crypto/tokens.ts::generateToken()

### Related Documents
- tasks/my-task (Auth Service Refactoring)

Prerequisites

Code must be indexed first:

git kb index