explain

Overview

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

When to Use

Run when the goal is understanding a file, directory, or flow. Pick --depth shallow for a quick orientation and the default deep when the reader will change the code next.

Invocation

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

Design Decisions

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

Improvements

## 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.

## Common Rationalizations

- "The name says Strategy, so it is the Strategy pattern": a pattern claim needs the interface and its implementations in view. Cite the `file:line` that shows it.
- "The rationale is obvious, I will state it": invented rationale reads as fact. Cite a comment, commit, or ADR, or say the reason is unclear.
- "The diagram looks right": Mermaid that fails to parse renders nothing. Read it back and check every node and edge against the code.
- "Every helper deserves a line": a directory explanation covers the public API and responsibilities. Internal helpers stay out.
- "An improvement section looks thorough": "No improvements needed" is valid. Each suggestion names a rule.

## Red Flags

- Stop and ask which code to explain when there is no argument and no file was discussed.
- Stop and re-read the source when a diagram node names a function or module that Grep cannot find.
- Stop and mark the decision as unclear when no comment, commit message, or ADR supports a stated rationale.
- Stop at step 3 when `--depth shallow` was passed.

## Verification

- The output follows the Output template with Purpose, Architecture, and, in deep mode, every remaining section.
- Every `file:line` in the Patterns and Improvements tables opens to the cited code.
- Every Mermaid block starts with a valid diagram type such as `graph TD`, `sequenceDiagram`, `flowchart`, or `classDiagram`.
- Every improvement row names a file under [`rules/`](../../rules), or the table holds the single "No improvements needed." row.

## 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.