---
name: explain
description: "Use when explaining code, concepts, patterns, or architecture: engineer-grade technical explanations with 3-tier depth control, ASCII diagrams, and execution traces."
effort: high
argument-hint: "<topic>|--depth brief|standard|deep"
tags: [explanation, teaching, analysis, architecture]
---



# Explain

Engineer-grade technical explanations of code, concepts, patterns, and architecture. 3-tier depth control scales detail to what the developer needs. Anchored in the actual codebase with `file:line` references, ASCII diagrams, and execution traces.

## When to Use

- "How does this work?", "What is this?", "Why does this do X?", "Trace this."
- NOT for generating documentation -- use `/ai-write`.
- NOT for writing/fixing code -- use `ai-build agent` or `/ai-debug`.

## Process

### 1. Identify subject

Classify into: Code, Concept, Pattern, Architecture, Error, or Difference. If ambiguous, ask ONE clarifying question.

### 2. Search codebase

Use Grep/Glob to find real instances. Codebase examples with `file:line` references are primary evidence. If not found, use generic example in project's stack and note it.

### 3. Select depth

| Depth | Trigger cues | Sections |
|-------|-------------|----------|
| Brief | "TL;DR", "brief", "short" | Summary + Walkthrough (3-5 steps) |
| Standard | General question (DEFAULT) | Summary + Walkthrough + Diagram + Gotchas + Trace |
| Deep | "deep dive", "everything", "teach me" | All above + Context Map + Complexity Notes |

### 4. Deliver explanation

**Summary** (all depths): 1-2 technical sentences -- what it does and why it exists.

**Walkthrough** (all depths): numbered steps with `file:line` references, following execution order. Brief: 3-5 steps max.

**Diagram** (standard+deep): ASCII art reflecting actual code structure. Choose type: data flow, call chain, state machine, sequence. Width under 70 chars. No Mermaid.

**Gotchas** (standard+deep): specific pitfalls in this code -- edge cases, performance traps, concurrency hazards. Not generic advice.

**Trace It** (standard+deep): execution trace through a concrete scenario. Show data transformation at each step, highlight decision points.

**Context Map** (deep only): when to use, when NOT to use, alternatives with tradeoff comparison.

**Complexity Notes** (deep only): cyclomatic complexity, nesting depth, time/space complexity of hot paths, concurrency assessment.

### 5. Follow-up

- "What about X?" -- extend at same depth.
- "Go deeper" -- increase one level, deliver only new sections.
- "Trace a different path" -- re-run Trace with different scenario.
- "Show me in my code" -- find the concept via Grep/Glob.

## Quick Reference

```
/ai-explain <topic>                  # standard depth (default)
/ai-explain <topic> --depth brief    # summary + walkthrough only
/ai-explain <topic> --depth deep     # all sections including complexity
```

## Common Mistakes

- Over-explaining standard concepts -- assume technical competence.
- Using Mermaid diagrams -- always ASCII art for terminal readability.
- Generic gotchas ("be careful with null") -- must be specific to the code under review.
- Using "basically", "simply", "just" -- these minimize real complexity.

## Integration

- Shared by `/ai-guide` for teaching mode.
- References actual codebase via Grep/Glob, not idealized examples.
- Read-only -- never writes code, tests, or documentation.

## References

- `.agents/skills/guide/SKILL.md` -- uses explain for teaching interactions.
- `.agents/skills/verify/SKILL.md` -- architecture assessment mode.
$ARGUMENTS