---
name: explain
description: This skill should be used when the user asks to "explain", "how does X work", "what does X do", or wants a deep-dive explanation of code.
category: development
argument-hint: [file-or-directory]
user-invocable: true
---

Explain `$ARGUMENTS` in depth by tracing the actual source code.

## Methodology

Follow this trace sequence — do not guess or summarize from memory. Read every file you reference.

1. **Locate the target.** Resolve `$ARGUMENTS` to a concrete file or directory.
   - If it is a file path, read it.
   - If it is a directory, list its contents and identify the main entry point(s) (index file, main module, `__init__.py`, etc.). Explain the module as a whole.
   - If it is a concept or function name (not a path), use Grep to find where it is defined, then read that file.
   - If nothing is found, tell the user the target could not be located and ask for clarification.

2. **Identify entry points.** Find the public API, exported functions, CLI entry point, or route handler — wherever external callers interact with this code.

3. **Trace call chains.** Starting from each entry point, follow the execution path inward:
   - What functions are called, in what order?
   - What data is passed between them?
   - Where does branching or error handling occur?

4. **Map data flow.** Track how inputs are transformed into outputs:
   - What are the input types/shapes?
   - What intermediate transformations happen?
   - What is returned or emitted?

5. **Catalog dependencies.** List every import, external library call, or service interaction. For each one, note what role it plays. Stop tracing when you hit external library internals or framework plumbing — describe what the external call does, not how it is implemented.

6. **Identify design decisions.** Note architectural choices, patterns (factory, observer, middleware, etc.), and any non-obvious trade-offs. If something looks unusual, explain why it might have been done that way.

## Output Format

Structure the explanation as follows:

### Purpose
One to three sentences: what this code does and why it exists.

### How It Works
Step-by-step walkthrough of the execution flow. Use numbered steps. Reference specific functions and files by name.

### Key Dependencies
Bullet list of libraries, services, or internal modules this code depends on, and what each provides.

### Design Decisions
Notable architectural choices, trade-offs, or patterns — and the likely reasoning behind them.

### File References
List every file that is essential for understanding this code, with absolute paths. This lets the reader navigate directly to the relevant source.

## Depth Guidance

- Trace until you reach external libraries, framework internals, or standard library calls. Describe what those do; do not trace into their source.
- If the target is large (many files, deep call trees), prioritize the main execution path first, then cover secondary paths.
- If the target has tests, reference them — they often clarify intended behavior.

## Edge Cases

- **File does not exist:** Tell the user and suggest similar files if any match partially.
- **Directory given:** Explain the module/package as a whole — purpose, structure, key files, and how they relate.
- **Vague target (e.g., "the auth system"):** Use Grep to find relevant files, then explain the subsystem.
- **Very large codebase target:** Focus on the top-level architecture and main flow. Offer to drill deeper into specific parts.
