---
description: Deep codebase investigation to understand architecture, trace functionality, find implementations, and analyze code patterns
allowed-tools: Task, AskUserQuestion, Bash, Read, TodoWrite, Glob, Grep
---

## Mission

Launch the codebase-detective agent to perform comprehensive code analysis, investigation, and navigation across complex codebases. This command helps understand how code works, find specific implementations, trace functionality flow, and analyze architectural patterns.

## Analysis Request

$ARGUMENTS

## When to Use This Command

Use `/analyze` when you need to:

- **Understand Architecture**: How is authentication implemented? What's the database layer structure?
- **Find Implementations**: Where is the user registration logic? Which file handles payments?
- **Trace Functionality**: Follow the flow from API endpoint to database
- **Debug Issues**: Why isn't the login working? Where is this error coming from?
- **Find Patterns**: Where are all the API calls made? What components use Redux?
- **Analyze Dependencies**: What uses this service? Where is this utility imported?

## How It Works

This command launches the **codebase-detective** agent, which:

1. Uses semantic code search (MCP claude-context) when available
2. Falls back to standard grep/find/rg tools when needed
3. Traces imports and dependencies across files
4. Analyzes code structure and patterns
5. Provides exact file locations with line numbers
6. Explains code relationships and flow

## Instructions

### Step 1: Understand the Request

Parse the user's analysis request from $ARGUMENTS:

- What are they trying to understand?
- What specific code/functionality are they looking for?
- What's the context (debugging, learning, refactoring)?

### Step 2: Launch codebase-detective Agent

Use the Task tool to launch the agent:

```
Task(
  subagent_type: "code-analysis:detective",
  description: "Analyze codebase for [brief description]",
  prompt: `
    Investigate the following in the codebase:

    [User's analysis request from $ARGUMENTS]

    Working directory: [current working directory]

    Please provide:
    1. Exact file locations with line numbers
    2. Code snippets showing the implementation
    3. Explanation of how the code works
    4. Related files and dependencies
    5. Code flow/architecture diagram if complex

    Use semantic search (claude-context MCP) if available, otherwise
    use grep/ripgrep/find for pattern matching.
  `
)
```

### Step 3: Present Results

After the agent completes:

1. **Summarize Findings**: Key files, main implementation locations
2. **Show Code Structure**: How components relate to each other
3. **Provide Next Steps**: Suggestions for what to do with this information
4. **Offer Follow-up**: Ask if they want deeper analysis of specific parts

## Example Usage

### Example 1: Finding Authentication Logic

```
User: /analyze Where is user authentication handled?

Agent launches with prompt:
"Find and explain the authentication implementation. Include:
- Login endpoint/handler
- Token generation/validation
- Authentication middleware
- Session management
- Related security code"

Results:
- src/auth/login.handler.ts:23-67 (login endpoint)
- src/middleware/auth.middleware.ts:12-45 (JWT validation)
- src/services/token.service.ts:89-120 (token generation)
```

### Example 2: Tracing Bug

```
User: /analyze The user profile page shows "undefined" for email field

Agent launches with prompt:
"Trace the user profile email display issue:
1. Find the profile page component
2. Locate where email data is fetched
3. Check how email is passed to the component
4. Identify where 'undefined' might be introduced"

Results:
- Identified missing null check in ProfilePage.tsx:156
- Found API returns 'e-mail' but code expects 'email'
- Provided exact line numbers for the mismatch
```

### Example 3: Understanding Architecture

```
User: /analyze How does the payment processing flow work?

Agent launches with prompt:
"Map out the complete payment processing flow:
1. Entry point (API endpoint or UI trigger)
2. Validation and business logic
3. Payment gateway integration
4. Database persistence
5. Success/failure handling
6. Related services and utilities"

Results:
- Flow diagram from checkout button to confirmation
- 7 key files involved with their roles
- External dependencies (Stripe SDK)
- Error handling strategy
```

## Tips for Effective Analysis

1. **Be Specific**: Instead of "analyze the codebase", ask "where is the email validation logic?"
2. **Provide Context**: Mention if you're debugging, refactoring, or learning
3. **Ask Follow-ups**: After initial results, drill deeper into specific files
4. **Use for Navigation**: Get oriented in unfamiliar codebases quickly

## Output Format

The agent will provide:

```
📍 Location Report: [What was analyzed]

**Primary Files**:
- path/to/main/file.ts:45-67 - [Brief description]
- path/to/related/file.ts:23 - [Brief description]

**Code Flow**:
1. Entry point: [File:line]
2. Processing: [File:line]
3. Result: [File:line]

**Related Components**:
- [Component name] - [Purpose]
- [Service name] - [Purpose]

**How to Navigate**:
[Commands to explore the code further]

**Recommendations**:
[Suggestions based on analysis]
```

## Success Criteria

The command is successful when:

1. ✅ User's question is fully answered with exact locations
2. ✅ Code relationships and flow are clearly explained
3. ✅ File paths and line numbers are provided
4. ✅ User can navigate to the code and understand it
5. ✅ Follow-up questions are anticipated and addressed

## Notes

- The codebase-detective agent is optimized for speed and accuracy
- It will use the best available tools (MCP search or grep/ripgrep)
- Results include actionable next steps
- Can handle complex, multi-file investigations
- Excellent for onboarding to new codebases