Explain Code

---
name: explain-code
description: "Explains code with multiple levels of detail — high-level purpose, line-by-line walkthrough, data flow diagrams, and design rationale. Use when onboarding to unfamiliar code or trying to understand complex logic."
argument-hint: "[file, function, or module to explain]"
allowed-tools: Read, Grep, Glob, Bash(git log*), Bash(git blame*)
---

# Code Explanation

## Instructions

### Step 1: Identify the Target
Read the specified file, function, or module completely. Also read:
- Any imports/dependencies it uses
- Any files that import/call it (to understand usage context)
- Recent git history for the file: `git log --oneline -10 <file>`

### Step 2: Provide Multi-Level Explanation

#### Level 1 — One-Sentence Summary
What does this code do in plain English? A non-technical person should understand this.

#### Level 2 — High-Level Overview
- **Purpose**: What problem does it solve?
- **Inputs**: What goes in? (parameters, config, env vars, external data)
- **Outputs**: What comes out? (return values, side effects, events emitted)
- **Dependencies**: What does it rely on?
- **Callers**: Who uses this? In what context?

#### Level 3 — Detailed Walkthrough
Walk through the code section by section:
- Explain the logic flow with numbered steps
- Highlight non-obvious decisions ("this uses X instead of Y because...")
- Note any error handling and what triggers each path
- Explain any performance-sensitive sections

#### Level 4 — Data Flow Diagram
Create an ASCII diagram showing:
```
[Input] → [Processing Step 1] → [Processing Step 2] → [Output]
                ↓                       ↓
         [Side Effect 1]         [Side Effect 2]
```

### Step 3: Highlight Key Details
- **Tricky Parts**: Code that might confuse a new reader
- **Assumptions**: Implicit assumptions the code makes
- **Edge Cases**: How are boundary conditions handled?
- **History**: Why was it written this way? (use `git blame` for context)

### Step 4: Related Code
List the most important related files/functions that someone exploring this code should read next.

---

## Output Style
- Use clear section headers
- Include code snippets with line references
- Use analogies where helpful
- Adjust technical depth based on the complexity of the code