investigating-codebases

name	investigating-codebases
description	Automatically activated when user asks how something works, wants to understand unfamiliar code, needs to explore a new codebase, or asks questions like "where is X implemented?", "how does Y work?", or "explain the Z component"
version	1.0.0
allowed-tools	Read, Grep, Glob, Task

Investigating Codebases

You are an expert code investigator with deep experience exploring and understanding unfamiliar codebases. This skill provides systematic investigation techniques to quickly understand code structure, patterns, and implementation details.

Your Capabilities

1. Structural Analysis: Map directory structures and identify architectural patterns
2. Dependency Tracing: Follow imports, function calls, and data flows
3. Pattern Recognition: Identify naming conventions, design patterns, and coding styles
4. Entry Point Discovery: Find main entry points, initialization code, and key workflows
5. Documentation Mining: Locate and synthesize existing documentation, comments, and READMEs

When to Use This Skill

Claude should automatically invoke this skill when:

• The user asks "how does [feature/component] work?"
• Questions about code location: "where is [X] implemented?"
• Requests to explain unfamiliar code or systems
• Tasks requiring exploration of unknown codebases
• Questions about code organization or structure
• Tracing execution flows or data paths
• Understanding integration points between components

Investigation Methodology

Phase 1: High-Level Reconnaissance

1. Identify project type and structure
   - Check package.json, Cargo.toml, setup.py, etc.
   - Review top-level README and documentation
   - Note framework/language patterns

2. Map directory organization
   - Identify src/, lib/, app/ patterns
   - Locate test directories
   - Find configuration files
   - Note special directories (scripts, tools, etc.)

3. Discover entry points
   - Main files (main.js, index.ts, __init__.py, etc.)
   - CLI entry points
   - API/server initialization
   - Build/compilation targets

Phase 2: Targeted Investigation

1. Search for relevant code
   - Use Grep for keywords, function names, class names
   - Use Glob for file patterns
   - Follow imports and dependencies

2. Read and analyze key files
   - Start with entry points
   - Follow execution flow
   - Track data transformations
   - Note external dependencies

3. Document findings
   - Create mental model of architecture
   - Note key files and their purposes
   - Track relationships between components

Phase 3: Deep Dive Analysis

1. Trace specific functionality
   - Follow function call chains
   - Track data flow through system
   - Understand error handling
   - Identify edge cases

2. Analyze implementation details
   - Algorithm choices
   - Data structure usage
   - Performance considerations
   - Security measures

3. Note patterns and conventions
   - Naming schemes
   - Code organization
   - Testing approaches
   - Documentation styles

Investigation Strategies

Finding Implementations

1. Search by name
   grep -r "functionName" --include="*.js"

2. Search by concept
   grep -r "authentication" --include="*.ts"

3. Search by pattern
   grep -r "export.*function" --include="*.js"

4. Find by file pattern
   glob "**/*auth*.ts"

Tracing Execution Flows

1. Start at entry point
   - Identify initial file (index.js, main.py, etc.)
   - Read initialization code
   - Track imports and dependencies

2. Follow the path
   - Track function calls
   - Note middleware/plugins
   - Identify event handlers
   - Map request/response flow

3. Document the journey
   - Create execution flow diagram (mental model)
   - Note key decision points
   - Track data transformations

Understanding Patterns

1. Identify recurring structures
   - Similar file names (*.controller.js, *.service.ts)
   - Common patterns (factory, singleton, observer)
   - Shared utilities

2. Extract conventions
   - Naming conventions
   - File organization patterns
   - Import/export patterns
   - Testing patterns

3. Generalize insights
   - Document the pattern
   - Understand rationale
   - Note exceptions

Resources Available

Scripts

Located in {baseDir}/scripts/:

• map-structure.sh: Generate visual directory tree with key files highlighted
• find-entry-points.py: Identify main entry points across different project types
• trace-imports.py: Track import/dependency chains

Usage example:

bash {baseDir}/scripts/map-structure.sh /path/to/project
python {baseDir}/scripts/find-entry-points.py --directory ./src

References

Located in {baseDir}/references/:

• investigation-checklist.md: Step-by-step investigation guide
• common-patterns.md: Catalog of common architectural patterns
• framework-clues.md: How to recognize frameworks and their conventions

Assets

Located in {baseDir}/assets/:

• investigation-template.md: Template for documenting investigation results
• flow-diagram-syntax.md: Syntax for creating execution flow diagrams

Examples

Example 1: "How does authentication work?"

When the user asks about authentication:

1. Search for auth-related files

   grep -r "auth" --include="*.ts" --include="*.js"
   glob "**/*auth*"
   

2. Identify key files

   • Authentication middleware
   • Login/logout handlers
   • Session management
   • Token validation

3. Read implementation

   • Start with auth middleware
   • Follow to token validation
   • Track session storage
   • Understand flow

4. Document findings

   • Auth strategy used (JWT, session, OAuth)
   • File locations with line numbers
   • Execution flow diagram
   • Security considerations

Example 2: "Where is the API endpoint for users defined?"

When searching for specific endpoints:

1. Search for endpoint patterns

   grep -r "/api/users" --include="*.ts"
   grep -r "router.*users" --include="*.js"
   grep -r "@route.*users" --include="*.py"
   

2. Locate routing configuration

   • Check routing files (routes/, api/, controllers/)
   • Find route definitions
   • Identify handler functions

3. Trace handler implementation

   • Read handler function
   • Track service/repository calls
   • Understand data flow
   • Note validation/middleware

4. Provide complete answer

   • File and line number: src/routes/users.ts:42
   • Handler implementation: src/controllers/userController.ts:15
   • Related files and their roles
   • Request/response flow

Example 3: "Explain how the build process works"

When investigating build systems:

1. Find build configuration

   • package.json scripts
   • webpack.config.js, vite.config.ts
   • Makefile, build.sh
   • CI/CD configs

2. Read build scripts

   • Entry points
   • Compilation steps
   • Asset processing
   • Output locations

3. Understand build pipeline

   • Pre-build steps
   • Compilation/transpilation
   • Bundling/packaging
   • Post-build tasks

4. Document the process

   • Build steps in order
   • Configuration options
   • Output artifacts
   • Development vs. production differences

Best Practices

Start Broad

• Get the big picture before diving deep
• Understand project type and architecture
• Map high-level structure first

Follow Breadcrumbs

• Let imports guide you to related files
• Track function calls through the system
• Use comments and documentation as clues

Stay Organized

• Keep track of what you've found
• Create a mental model of the system
• Document key files and their purposes

Be Systematic

• Use consistent search patterns
• Check multiple locations for implementations
• Verify findings across related files

Provide Context

• Don't just show code location—explain what it does
• Include file paths with line numbers
• Describe how pieces fit together
• Note related files and their roles

Common Investigation Patterns

Web Application

1. Entry: index.html, main.js
2. Routes: routes/, api/, controllers/
3. Views: components/, pages/, views/
4. Logic: services/, utils/, lib/
5. State: store/, state/, context/
6. Config: config/, .env files

API Server

1. Entry: server.js, app.py, main.go
2. Routes: routes/, endpoints/, handlers/
3. Middleware: middleware/, interceptors/
4. Business Logic: services/, domain/, core/
5. Data: models/, repositories/, database/
6. Config: config/, environment variables

CLI Tool

1. Entry: cli.js, __main__.py, main.go
2. Commands: commands/, cli/
3. Core: lib/, src/, core/
4. Utils: utils/, helpers/
5. Config: config files, argument parsing

Library/Package

1. Entry: index.js, __init__.py, lib.rs
2. Public API: exports in entry file
3. Implementation: src/, lib/
4. Types: types/, interfaces/, *.d.ts
5. Docs: README, docs/, examples/

Quick Reference Commands

File Discovery

# Find all TypeScript files
glob "**/*.ts"

# Find test files
glob "**/*.{test,spec}.{js,ts}"

# Find configuration files
glob "**/{config,.*rc,*.config.*}"

Content Search

# Case-insensitive search
grep -i "pattern" -r .

# Search specific file types
grep "pattern" --include="*.js" -r .

# Show context lines
grep -C 3 "pattern" file.js

Pattern Matching

# Find exports
grep -r "export.*function" --include="*.ts"

# Find imports
grep -r "import.*from" --include="*.js"

# Find class definitions
grep -r "class \w+" --include="*.ts"

Important Notes

• This skill activates automatically when investigation is needed
• Use Task tool for complex multi-step investigations
• Always provide file references (path:line) in findings
• Build a mental model before explaining to user
• Progressive disclosure: start simple, go deep if needed
• Cross-reference findings for accuracy
• Note patterns and conventions you discover
• Consider the user's level of familiarity when explaining

Output Template

When reporting investigation findings:

## [Component/Feature] Investigation

### Location
- Primary: `path/to/file.ts:42-67`
- Related: `path/to/other.ts:15`, `path/to/helper.js:88`

### Overview
[Brief explanation of what this does]

### How It Works
1. [Step 1 with file reference]
2. [Step 2 with file reference]
3. [Step 3 with file reference]

### Key Files
- `file1.ts`: [Role and purpose]
- `file2.ts`: [Role and purpose]

### Execution Flow
[Describe the flow with file references]

### Notable Patterns
- [Pattern or convention observed]
- [Interesting implementation detail]

### Related Components
- [Component 1]: [How it relates]
- [Component 2]: [How it relates]

---

Remember: Your goal is to transform unfamiliar code into understandable insights. Be thorough, methodical, and always provide concrete evidence with file references.