Codebase Exploration Skill

Codebase Exploration

Purpose

Specializes in systematic codebase exploration and discovery. Uses advanced search techniques, pattern recognition, and code analysis to quickly understand unfamiliar code, locate specific implementations, map architectural patterns, and answer location-based questions about code.

When to Use

• Exploring an unfamiliar codebase for the first time
• Need to find where specific functionality is implemented
• Looking for examples of a pattern across the codebase
• Understanding how components interact
• Locating all usages of a particular API or pattern
• Mapping architectural organization
• Finding similar code across the project
• Questions like "Where is X?", "Which file has Y?", "Find code that does Z"

Quick Start

Invoke this skill when:

• Exploring an unfamiliar codebase for the first time
• Need to find where specific functionality is implemented
• Looking for examples of a pattern across the codebase
• Understanding how components interact
• Questions like "Where is X?", "Which file has Y?", "Find code that does Z"

Do NOT invoke when:

• Debugging a known bug (use debugger-skill)
• Refactoring code (use refactoring-specialist-skill)
• Reviewing code quality (use code-reviewer-skill)
• Writing new code from scratch (use appropriate developer skill)

Thoroughness Levels

Quick (Fast, broad strokes)

• File structure overview
• High-level pattern matching
• Directory organization
• Main entry points
• ~30 seconds

Medium (Balanced depth)

• Detailed file examination
• Cross-file pattern discovery
• Architectural mapping
• Common patterns analysis
• ~2-3 minutes

Very Thorough (Deep dive)

• Exhaustive code analysis
• Complex pattern matching
• Dependency tracing
• Edge case discovery
• ~5-10 minutes

Decision Framework

Search Strategy Selection

Tool Selection

Approach by Question Type

"Where is X implemented?" 1. Search for X by name: rg "X|x" 2. Search for related terms: rg "related|terms" 3. Check obvious locations: ls src/X/ 4. Look in tests: rg "X" tests/

"How does Y work?" 1. Find Y's definition 2. Find Y's usage 3. Trace the flow 4. Understand dependencies

"Which files use Z?" 1. Search for imports of Z 2. Use LSP find-references 3. Search for Z's methods being called

Core Capabilities

Search Strategies

Pattern-Based Search

• Find by naming conventions
• Locate by code patterns
• Discover by architectural markers
• Identify by file organization

Context-Aware Search

• Understand code relationships
• Map dependencies
• Trace execution flows
• Find related components

Multi-Angle Discovery

• Search by functionality
• Search by structure
• Search by naming
• Search by patterns

Exploration Workflow

Step 1: Orient

• What are we looking for?
• Why do we need it?
• What level of detail is needed?
• Which thoroughness level is appropriate?

Step 2: Map Structure

• Identify top-level organization
• Find key markers (entry points, config files)
• Note directory naming patterns

Step 3: Execute Search

• Choose appropriate tools
• Use multiple search angles
• Document findings

Step 4: Analyze & Synthesize

• Connect the dots
• Identify patterns
• Prioritize findings

Best Practices

Start Broad, Then Narrow

1. First: Get the lay of the land (tree -L 2, ls -la src/) 2. Second: Identify patterns (fd -e ts, rg -c "class|function") 3. Third: Target specific areas

Use Multiple Search Angles

• Search by name: fd auth
• Search by content: rg "authentication"
• Search by structure: ast-grep --pattern "class $NAME"
• Search by symbols: lsp_workspace_symbols

Follow the Breadcrumbs

1. Check imports to find dependencies 2. Use LSP to find references 3. Look at file location for architectural clues 4. Check git history for context

Document as You Go

# Authentication Flow
1. Entry: src/middleware/auth.ts
2. Token validation: src/services/jwt.service.ts  
3. User lookup: src/repositories/user.repository.ts
4. Guards: src/guards/auth.guard.ts

Anti-Patterns

• Don't Search Without Context: Understand what you're looking for first
• Don't Ignore File Structure: Always check directory organization
• Don't Rely on Single Search Method: Use multiple approaches
• Don't Forget About Tests: Search test files for real usage
• Don't Skip Configuration Files: Check config early

Related Skills

• Use [[debugger-skill]] when exploration reveals bugs
• Use [[architect-reviewer-skill]] to evaluate discovered patterns
• Use [[refactoring-specialist-skill]] to improve found code
• Use [[technical-advisory-skill]] for complex architectural questions

Additional Resources

• Detailed Technical Reference: See REFERENCE.md
• Code Examples & Patterns: See EXAMPLES.md

Codebase Exploration - Code Examples & Patterns

Example 1: Finding Authentication in Express App

Question: "Where is user authentication handled?"

Quick Search:

$ rg -l "auth" src/
src/middleware/auth.ts
src/routes/auth.routes.ts  
src/services/auth.service.ts
src/models/user.model.ts

Medium Depth:

$ rg -A 5 "middleware.*auth"
src/routes/protected.routes.ts:
router.use(authMiddleware);  # Applied to routes

$ rg "class.*Auth|function.*auth"
src/middleware/auth.ts:
export const authMiddleware = async (req, res, next) => {
  // JWT validation
}

Finding: Authentication is in src/middleware/auth.ts, uses JWT, applied in route files

Example 2: Understanding Data Flow in React App

Question: "How does data flow from API to UI?"

Thoroughness: Medium

Search Process:

# Find API calls
$ rg "fetch|axios|api\." src/
src/services/api.service.ts
src/hooks/useData.ts

# Find state management
$ rg "useState|useQuery|createSlice"
src/hooks/useData.ts  # React Query
src/store/dataSlice.ts  # Redux

# Find components
$ fd -e tsx . src/components

Finding: API → Service → React Query Hook → Component

Example 3: Locating Database Queries

Question: "Find all database queries"

Thoroughness: Very Thorough

Search Process:

# Find ORM usage
$ rg "from.*Model.*import|Model\.|@Entity"

# Find raw SQL
$ rg "SELECT|INSERT|UPDATE|DELETE" --type ts

# Find query builders
$ rg "query|find|where\(|create\("

# Analyze patterns
$ rg -c "\.find\(|\.findOne\(|\.create\(" src/**/*.ts | sort -t: -k2 -rn

Finding: Queries concentrated in src/repositories/, using TypeORM

Example 4: Mapping Component Hierarchy

Question: "What's the component structure?"

# Find all components
$ fd -e tsx src/components

# Find component imports
$ rg "import.*from.*components" src/

# Find component usage patterns
$ ast-grep --pattern "<$COMPONENT $$$>"

Example 5: Finding Error Handling Patterns

# Find try-catch blocks
$ rg -A 3 "try {"

# Find error classes
$ rg "class.*Error|extends Error"

# Find error middleware
$ rg "error.*middleware|middleware.*error"

# Find error logging
$ rg "console.error|logger.error|log.error"

Common Search Commands Reference

File Discovery

# Find by name pattern
fd "auth" src/
fd -e ts -e tsx src/

# Find by content
rg -l "authentication" src/

# Find by structure
tree -L 3 src/

Pattern Matching

# Function definitions
rg "function \w+\(" src/
rg "const \w+ = \(" src/
rg "async function" src/

# Class definitions
rg "class \w+" src/
ast-grep --pattern "class $NAME { $$$ }"

# Interface/Type definitions
rg "interface \w+|type \w+ =" src/

Dependency Analysis

# What imports this file?
rg "from.*filename"

# What does this file import?
rg "^import" src/path/to/file.ts

# External dependencies
rg "from ['\"][^.]" src/

Git History Analysis

# Recently changed files
git log --name-only --since="1 week ago" --pretty=format: | sort | uniq

# Most changed files (hotspots)
git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20

# Who worked on this area
git log --format="%an" -- src/auth/ | sort | uniq -c | sort -rn

Quick Reference: Search by Question Type

Codebase Exploration - Technical Reference

Search Patterns by Use Case

Finding Authentication

Quick (grep/rg):

# Find auth-related files
rg -l "auth|login|session" --type ts

# Find middleware
rg "middleware.*auth|auth.*middleware"

# Find route guards
rg "guard|protect|require.*auth"

Medium (deeper context):

# Find auth implementations
rg -A 5 "class.*Auth|interface.*Auth"

# Find password handling
rg "password|hash|bcrypt|argon"

# Find session management
rg "session|token|jwt"

Very Thorough (comprehensive):

# Trace full auth flow
rg -C 10 "login.*request"
ast-grep --pattern "async function login($$$) { $$$ }"
lsp_find_references on auth symbols

Finding Data Models

Quick:

# Locate model files
fd model
fd -e ts -e js . src/models

# Find class definitions
rg "class.*Model|interface.*Model"

Medium:

# Find schemas/types
rg "type.*Schema|interface.*Type|class.*Entity"

# Find database decorators
rg "@Entity|@Table|@Model"

# Find validation rules
rg "validator|validate|schema|zod|yup"

Very Thorough:

# Map all data structures
ast-grep --pattern "interface $NAME { $$$ }"
ast-grep --pattern "class $NAME { $$$ }"
lsp_document_symbols on model files

Finding API Endpoints

Quick:

# Find route definitions
rg "router\.|route|@Get|@Post|@Put|@Delete"

# Find controller files
fd controller
rg "class.*Controller"

Medium:

# Find endpoint handlers
rg -A 10 "@Get\(|@Post\(|router.get|router.post"

# Find middleware chain
rg "use\(|middleware|guard"

# Find request/response types
rg "Request|Response|Dto|Input|Output"

Very Thorough:

# Trace full request flow
rg -C 15 "router\.(get|post|put|delete)"
ast-grep --pattern "router.$METHOD('$PATH', $$$)"
# Find all references to route handlers

Finding State Management

Quick:

# Find store/state files
fd store state
rg "createStore|createSlice|useState|Vuex|Redux"

Medium:

# Find actions and mutations
rg "action|mutation|dispatch|commit"

# Find selectors
rg "selector|useSelector|mapState"

# Find context providers
rg "Context|Provider|createContext"

Very Thorough:

# Map state architecture
ast-grep --pattern "const $NAME = createSlice({ $$$ })"
rg -C 20 "combineReducers|configureStore"
# Trace state flow from components to store

Exploration Techniques

File Structure Analysis

# Quick overview
tree -L 2 src/

# Count by type
find src/ -type f | sed 's/.*\.//' | sort | uniq -c | sort -nr

# Find largest files (potential hotspots)
find . -type f -exec du -h {} + | sort -rh | head -20

# Find recently changed files
git log --name-only --pretty=format: --since="1 month ago" | sort | uniq -c | sort -nr

Pattern Discovery

# Find common patterns
rg "^import.*from" | cut -d"'" -f2 | sort | uniq -c | sort -nr

# Find naming conventions
find src/ -name "*.ts" | sed 's/.*\///' | sed 's/\..*//' | sort

# Find architectural patterns
rg "class.*Service|class.*Controller|class.*Repository" | wc -l

Dependency Mapping

# Find imports
rg "^import.*from ['\"]\.\.?/"  # Internal imports
rg "^import.*from ['\"][^.]"    # External imports

# Find common dependencies
rg "^import.*from" | cut -d"'" -f2 | grep -v "^\." | sort | uniq -c | sort -nr

Code Hotspots

# Find files with most changes
git log --format=format: --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20

# Find files with most lines
find . -name "*.ts" -exec wc -l {} + | sort -rn | head -20

# Find complex files (many functions)
rg -c "function|const.*= \(" src/**/*.ts | sort -t: -k2 -rn

Exploration Reports

After exploration, summarize findings:

Format

# Codebase Exploration: [Topic]

## Question
[What we were looking for]

## Findings

### Primary Implementation
**File**: src/path/to/main.ts
**Purpose**: [What it does]
**Key Functions**:
- `functionA()`: [Description]
- `functionB()`: [Description]

### Supporting Files
**File**: src/path/to/helper.ts
**Purpose**: [Supporting role]

### Related Patterns
- Pattern A found in: file1, file2, file3
- Pattern B found in: file4, file5

## Architecture Notes
[How things connect, patterns observed]

## Next Steps
[Suggested further exploration or actions]