---
description: Explain code in detail - how it works, patterns used, and key concepts
allowed-tools: Read(*), Grep(*), Glob(*), Bash(git log:*)
argument-hint: [file-or-selection]
---

# Explain Command

Provide detailed, educational explanations of code.

## Technology Adaptation

**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)

Consult CLAUDE.md for:
- **Language**: To explain syntax and language-specific features
- **Frameworks**: To identify framework patterns and conventions
- **Project Patterns**: To explain project-specific architectures

## Instructions

1. **Identify Target**
   - If $ARGUMENTS provided: Explain that file/code
   - If user has selection: Explain selected code
   - Otherwise: Ask what needs explanation

2. **Analyze Code**
   - Read CLAUDE.md to understand project context
   - Use serena MCP to understand code structure
   - Identify patterns, algorithms, and design choices
   - Understand dependencies and relationships

3. **Provide Explanation**
   Include these sections:
   - **Purpose**: What this code does (high-level)
   - **How It Works**: Step-by-step breakdown
   - **Key Concepts**: Patterns, algorithms, principles used
   - **Dependencies**: What it relies on
   - **Important Details**: Edge cases, gotchas, considerations
   - **In Context**: How it fits in the larger system

4. **Adapt Explanation Level**
   - Use clear, educational language
   - Explain technical terms when first used
   - Provide examples where helpful
   - Reference CLAUDE.md patterns when relevant

## MCP Server Usage

### Serena MCP

**Code Navigation**:
- `find_symbol` - Locate symbols to explain
- `find_referencing_symbols` - Understand usage and relationships
- `get_symbols_overview` - Get file structure and organization
- `search_for_pattern` - Find related patterns

**Persistent Memory** (stored in `.serena/memories/`):
- Use `write_memory` to store complex explanations for future reference:
  - "explanation-algorithm-[name]"
  - "explanation-pattern-[pattern-name]"
  - "explanation-architecture-[component]"
- Use `read_memory` to recall past explanations of related code
- Use `list_memories` to find previous explanations

### Memory MCP (Knowledge Graph)

**Temporary Context** (in-memory, cleared after session):
- Use `create_entities` for code elements being explained
- Use `create_relations` to map relationships between components
- Use `add_observations` to document understanding

**Note**: After explanation, store reusable patterns in Serena memory.

### Context7 MCP
- Use `get-library-docs` for framework/library documentation and official explanations

## Output Format

```markdown
## Explanation: [Code/File Name]

### Purpose
[What this code accomplishes and why it exists]

### How It Works

#### Step 1: [High-level step]
[Detailed explanation]

```[language]
[Relevant code snippet]
```

#### Step 2: [Next step]
[Explanation]

### Key Concepts

#### [Concept 1]: [Name]
[Explanation of pattern/algorithm/principle]

#### [Concept 2]: [Name]
[Explanation]

### Dependencies
- **[Dependency 1]**: [What it provides and why needed]
- **[Dependency 2]**: [What it provides and why needed]

### Important Details
- **[Detail 1]**: [Edge case or consideration]
- **[Detail 2]**: [Gotcha or important note]

### In the Larger System
[How this fits into the project architecture from CLAUDE.md]

### Related Code
[Links to related files or functions]

### Further Reading
[References to documentation or patterns]
```

## Example Output Scenarios

### For a Function
- Explain algorithm and complexity
- Show input/output examples
- Highlight edge cases
- Explain why this approach was chosen

### For a Class
- Explain responsibility and role
- Show key methods and their purposes
- Explain relationships with other classes
- Highlight design patterns used

### For a Module
- Explain module's purpose in architecture
- Show public API and how to use it
- Explain internal organization
- Show integration points

## Guidelines

- Start with high-level understanding, then dive into details
- Use analogies when helpful
- Explain "why" not just "what"
- Reference CLAUDE.md patterns
- Be educational but concise
- Assume reader has basic programming knowledge
- Adapt detail level based on code complexity