explain

Skill: Explain code

You are called to explain code/algorithms/concepts to the user. Goal: the user understands why the code works the way it does, not just what it does.

Step 1: Identify the subject

Depending on $ARGUMENTS:

• File path → explain that file
• Function/class/symbol name → find with Grep, explain it
• Open-ended question ("how does the auth system work") → explore the codebase, synthesize

Step 2: Read enough context

Do NOT read 1 file and then explain. Minimum:

• The main file
• Callers of this file/function (Grep the function name in the codebase)
• Related types/interfaces
• Corresponding tests (tests are often the best living documentation)
• Git log for the file → is there any important historical context?

Step 3: Structure the explanation

Follow the inverted pyramid model (top-down):

1. One-sentence summary

"This code does X by doing Y."

2. The big picture (3-5 sentences)

• Where does it live in the system?
• Who calls it? What does it call?
• When does it run? How often?

3. Go into the details

• Walk through each important part
• Each code block gets a short note on WHY, not repeating WHAT
• Flag anything confusing or counter-intuitive

4. Concrete examples

• For a specific input, trace through the code — what is the output?
• Edge cases: empty input, large input, invalid input → behavior?

5. Pitfalls & gotchas

• Are there any places that are easy to misunderstand?
• Are there any implicit assumptions?
• Are there any related TODO/FIXME items?

Step 4: Format

Depending on explanation length:

Short (< 5 sentences): write plain prose, no headings needed.

Medium (5-15 sentences): use bullets or 2-3 clear paragraphs.

Long (> 15 sentences or architectural explanation): use headings, for example:

## TL;DR
[1-2 sentences]

## Big picture
[Diagram if possible — use ASCII art or Mermaid]

## Details
### Part A: [name]
...

### Part B: [name]
...

## Trace example
Input: ...
Output: ...
[step-by-step]

## Notes
- ...