ai-explain

name	ai-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

• .claude/skills/ai-guide/SKILL.md -- uses explain for teaching interactions.
• .claude/skills/ai-verify/SKILL.md -- architecture assessment mode. $ARGUMENTS