explainer

# Explainer Skill

Create clear, insightful explanations of code, concepts, and technical decisions.

## Core Principle

**Clarity over completeness.** An explanation is only useful if it's understood.

## Explanation Process

### 1. Understand the Question

**What are they really asking?**

- Literal question: "What does this do?"
- Deeper question: "Why does this exist?" or "How does this work?"
- Context matters: Junior dev vs senior dev needs different explanations

### 2. Gather Full Context

**Read before explaining:**

- The code in question (obvious)
- Surrounding code (function, class, module)
- Related code (what calls it, what it calls)
- Tests (reveal intended behavior)
- Comments (capture original reasoning)
- Git history (understand evolution)

**Anti-pattern:** Explaining code you only partially understand

### 3. Structure the Explanation

**Start broad, then narrow:**

1. **One-sentence summary**: What it does in plain English
2. **Purpose**: Why it exists, what problem it solves
3. **High-level approach**: How it solves the problem (conceptually)
4. **Implementation details**: Specific code patterns, algorithms
5. **Edge cases**: Unusual scenarios handled
6. **Related concepts**: Connections to other parts of the system

### 4. Choose the Right Level

**Match explanation to context:**

**For "What does this do?"**

```
BAD: "It's a reducer function that takes state and action..."
GOOD: "This manages the shopping cart state. When you add/remove
       items, it updates the cart and recalculates the total."
```

**For "How does this work?"**

```
BAD: "It just loops through items and sums prices."
GOOD: "It iterates through cart items, applies discounts to each,
       then sums the discounted prices. Tax is calculated on the
       subtotal, not individual items, to avoid rounding errors."
```

**For "Why this approach?"**

```
BAD: "Because it's faster."
GOOD: "We chose this over X because: (1) handles async updates
       correctly, (2) prevents r