---
name: explain
description: "Explain recent code changes in simple terms a junior dev can understand"
argument-hint: "[optional focus area or question about the changes]"
---

Explain the code changes that were just applied in this conversation. Break it down so a junior developer can fully understand what happened, why, and how it works.

## Workflow

### Step 1: Gather context

Look back through the conversation history and identify all code changes that were just made. This includes:
- Files created, edited, or deleted
- Functions added or modified
- Dependencies or imports changed
- Config changes

If `$ARGUMENTS` is provided, focus the explanation on that specific area or answer that specific question about the changes.

### Step 2: Explain — What did you do?

List every change that was made, file by file. For each file:
- What was the file before (or that it's new)
- What changed and where
- Use short code snippets to highlight the key parts (not the full file)

Keep it scannable. Use bullet points and headers.

### Step 3: Explain — Why did you do it?

For each change (or group of related changes), explain:
- What problem it solves
- Why this approach was chosen over alternatives
- What would happen if this change was NOT made

Connect the dots between changes. If file A was changed because of file B, say so.

### Step 4: Explain — How does it work?

This is the deep dive. Explain the logic step by step:
- Walk through the code flow as if you are tracing execution
- Use numbered steps: "First this happens, then this, then this..."
- Use simple analogies where helpful (e.g., "Think of this like a to-do list where...")
- If the logic involves data flow, show it visually with ASCII diagrams:

```
  User clicks button
       |
       v
  handleClick() runs
  API call to /api/save
  Response updates state
  Component re-renders with new data
```

- If there are important patterns (hooks, context, middleware, etc.), explain what they are and why they are used here
- Define any technical terms the first time you use them

### Step 5: Key takeaways

Summarize with 3-5 bullet points:
- The most important thing to remember
- Any gotchas or edge cases to watch out for
- Related concepts worth learning more about

## Writing Rules

- Use simple English. Short sentences. No jargon without explanation.
- Write like you are explaining to a teammate on their first week.
- Prefer concrete examples over abstract descriptions.
- Use "you" and "we" to keep it conversational.
- Use code snippets, ASCII diagrams, and step-by-step flows wherever they help.
- Do NOT assume the reader knows framework-specific concepts — explain them briefly.

## Step 6: Ask about saving

After the explanation is complete, ask:

> "Want me to save this explanation to a markdown file for future reference? (default: no)"

- If the user says **no** or does not respond, do nothing. Stop here.
- If the user says **yes**, ask where they want to save it. Suggest a sensible default path based on the project structure (e.g., `docs/explanations/` or `.notes/`).
- Save the explanation as a clean markdown file with a descriptive filename based on the topic (e.g., `auth-flow-explanation.md`).

## User Arguments

$ARGUMENTS