explain

Code explanation skill with educational depth. Analyzes code structure, traces data flow, identifies patterns, and produces Mermaid diagrams to make complex systems understandable.

Invocation

Invocation	Action
/explain	Explain the current file or most recently discussed code
/explain <path>	Explain a specific file or directory
/explain --depth shallow	High-level overview only
/explain --depth deep	Full analysis with data flow tracing and pattern identification

If no --depth is specified, default to deep.

---

Steps

1. Identify the target. Determine what to explain:

   • If no argument: use the most recently discussed file or ask for clarification.
   • If a file path: read the file.
   • If a directory path: read the directory listing, then read key files to understand the module.

2. High-level overview. Start with what the code does in plain language:

   • Purpose: what problem does this code solve?
   • Scope: what is included and what is delegated elsewhere?
   • Entry points: where does execution start?
   • Dependencies: what does this code depend on?

3. Architecture diagram. Generate a Mermaid diagram showing the component relationships:

   • For a single file: show the file's imports, exports, and how it connects to the rest of the system.
   • For a directory: show module boundaries, dependencies between modules, and data flow.
   • Use graph TD for hierarchical relationships, sequenceDiagram for request flows, classDiagram for type hierarchies.

4. Data flow trace. Follow data through the code:

   • Where does data enter the system?
   • What transformations happen at each step?
   • Where does data exit the system?
   • Generate a Mermaid sequenceDiagram or flowchart showing the data path.

5. Pattern identification. Identify design patterns used in the code:

   Pattern	What to look for
   Repository	Data access abstraction layer
   Strategy	Interchangeable algorithms behind a common interface
   Factory	Object creation delegated to a specialized function or class
   Observer	Event emitters, listeners, pub/sub
   Decorator	Wrapping behavior around existing functions or classes
   Middleware	Pipeline of functions processing a request sequentially
   State machine	Explicit state transitions with defined valid moves
   CQRS	Separate read and write models
   Dependency injection	Dependencies provided externally rather than created internally

   For each pattern found, explain why it was chosen and what alternative would look like.

6. Design decision analysis. For non-obvious design choices in the code:

   • What trade-off was made?
   • What would the alternative approach look like?
   • Why was this approach likely chosen?
   • Reference comments, commit messages, or ADRs if they exist.

7. Improvement suggestions. If the code has issues, note them:

   • Only suggest improvements that are concrete and actionable.
   • Reference the specific rule from ../../rules/ that applies.
   • Do not suggest improvements for code that is already well-structured. "No improvements needed" is valid output.

Shallow mode

When --depth shallow is specified, run only steps 1-3. Skip data flow tracing, pattern identification, design decision analysis, and improvement suggestions.

Output

## Explanation: <file or directory name>

### Purpose
<Plain-language description of what this code does and why it exists>

### Architecture
```mermaid
<component diagram>

Data Flow

<data flow diagram>

Patterns

Pattern	Location	Rationale
<name>	file:line	<why this pattern was chosen>

Design Decisions

1. <Decision>: <explanation of the trade-off and reasoning>

Improvements

File	Line	Suggestion	Rule
<path>	<line>	<what to change>	<rule reference>
		No improvements needed.

## Rules

- Explain for the reader's level. If the code is simple, keep the explanation short. If the code is complex, go deeper.
- Every Mermaid diagram must be valid syntax. Test by reading it back.
- Never fabricate design rationale. If the reason for a decision is unclear, say so.
- Do not explain language syntax unless the user appears to be learning the language.
- When explaining a directory, focus on the module's public API and responsibilities. Do not explain every internal helper.
- Improvements must reference specific rules. "This could be better" is not actionable.

## Related skills

- `/review` -- Review code for issues rather than explain it.
- `/assessment` -- Architecture completeness audit.
- `/investigate` -- Debug a specific problem in the code.
- `/plan` -- Plan changes to the code after understanding it.