Explain - Deep Code Explanation

Get a comprehensive explanation of code, files, directories, or architectural concepts. Automatically routes to the most relevant expert agent and uses modern CLI tools for analysis.

Arguments

$ARGUMENTS

• <target> - File path, function name, class name, directory, or concept
• --depth <shallow|normal|deep|trace> - Level of detail (default: normal)
• --focus <arch|flow|deps|api|perf> - Specific focus area

Architecture

/explain <target> [--depth] [--focus]
    |
    +-> Step 1: Detect & Classify Target
    |     +- File exists? -> Read it
    |     +- Function/class? -> ast-grep to find definition
    |     +- Directory? -> tokei for overview
    |     +- Concept? -> rg search codebase
    |
    +-> Step 2: Gather Context (parallel)
    |     +- structural-search skill -> find usages
    |     +- code-stats skill -> assess scope
    |     +- Find related: tests, types, docs
    |     +- Load: AGENTS.md, CLAUDE.md conventions
    |
    +-> Step 3: Route to Expert Agent
    |     +- .ts/.tsx -> typescript-expert or react-expert
    |     +- .py -> python-expert
    |     +- .vue -> vue-expert
    |     +- .sql/migrations -> postgres-expert
    |     +- agents/skills/commands -> claude-architect
    |     +- Default -> general-purpose
    |
    +-> Step 4: Generate Explanation
    |     +- Structured markdown with sections
    |     +- Mermaid diagrams (flowchart/sequence/class)
    |     +- Related code paths as file:line refs
    |     +- Design decisions and rationale
    |
    +-> Step 5: Integrate
          +- Offer to save to ARCHITECTURE.md (if significant)
          +- Link to /save if working on related task

Execution Steps

Step 1: Detect Target Type

# Check if target is a file
test -f "$TARGET" && echo "FILE" && exit

# Check if target is a directory
test -d "$TARGET" && echo "DIRECTORY" && exit

# Otherwise, search for it as a symbol

For files: Read directly with bat (syntax highlighted) or Read tool.

For directories: Get overview with tokei (if available):

command -v tokei >/dev/null 2>&1 && tokei "$TARGET" --compact || echo "tokei unavailable"

For symbols (function/class): Find definition with ast-grep:

# Try ast-grep first (structural)
command -v ast-grep >/dev/null 2>&1 && ast-grep -p "function $TARGET" -p "class $TARGET" -p "def $TARGET"

# Fallback to ripgrep
rg "(?:function|class|def|const|let|var)\s+$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code

Step 2: Gather Context

Run these in parallel where possible:

Find usages (structural-search skill):

# With ast-grep
ast-grep -p "$TARGET($_)" --json 2>/dev/null | head -20

# Fallback
rg "$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code -l

Find related files:

# Tests
fd -e test.ts -e spec.ts -e test.py -e spec.py | xargs rg -l "$TARGET" 2>/dev/null

# Types/interfaces
fd -e d.ts -e types.ts | xargs rg -l "$TARGET" 2>/dev/null

Load project conventions:

• Read AGENTS.md if exists
• Read CLAUDE.md if exists
• Check for framework-specific patterns

Step 3: Route to Expert Agent

Determine the best expert based on file extension and content:

Invoke via Task tool:

Task tool with subagent_type: "[detected]-expert"
Prompt includes:
  - File content
  - Related files found
  - Project conventions
  - Requested depth and focus

Step 4: Generate Explanation

The expert agent produces a structured explanation:

# Explanation: [target]

## Overview
[1-2 sentence summary of purpose and role in the system]

## Architecture

[Mermaid diagram - choose appropriate type]

### Flowchart (for control flow)
` ` `mermaid
flowchart TD
    A[Input] --> B{Validate}
    B -->|Valid| C[Process]
    B -->|Invalid| D[Error]
    C --> E[Output]
` ` `

### Sequence (for interactions)
` ` `mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: Response
` ` `

### Class (for structures)
` ` `mermaid
classDiagram
    class Component {
        +props: Props
        +state: State
        +render(): JSX
    }
` ` `

## How It Works

### Step 1: [Phase Name]
[Explanation with code references]

See: `src/module.ts:42`

### Step 2: [Phase Name]
[Explanation]

## Key Concepts

### [Concept 1]
[Explanation]

### [Concept 2

...