Explain

Explain code grouped by logical concepts rather than file-by-file.

Usage

/explain                          # Explain code related to current context
/explain --staged                 # Explain code in git staged files
/explain --all                    # Interactive: pick dirs/files to explain
/explain --code                   # Also explain language syntax and idioms
/explain --code --staged          # Staged files with syntax explanations

Flags

Workflow

1. Determine Scope

Empty scope handling:

• •--staged with no staged files: Report "No staged files found. Stage files with git add first, or use --all to pick files interactively."
• •--all with no source files found: Report "No source files found in this directory. Verify you are in the project root."
• •Default mode with no context: Ask the user to specify files (see table above).

2. Read and Analyze

Read all in-scope source files to understand the codebase. Skip binary files (images, compiled assets, .lock files), generated directories (node_modules/, build/, dist/), and files over 2000 lines (summarize their purpose from the first 50 lines instead).

3. Identify Concepts

Group code into logical concepts/features rather than explaining file-by-file. Examples of concepts:

• •"Authentication" — login flow, token management, session handling
• •"Database layer" — models, migrations, query helpers
• •"API routing" — endpoint definitions, middleware, request handling
• •"State management" — stores, reducers, selectors
• •"Error handling" — error types, recovery strategies, logging

Choose concept names that reflect what the code actually does — don't force-fit generic names.

4. Generate Explanations

For each concept:

• •Overview: What this concept does and why it exists
• •Key pieces: Detailed walkthrough of non-obvious parts — control flow, algorithms, edge cases, design decisions
• •Connections: How files in this concept relate to each other and to other concepts
• •Syntax notes (--code only): For notable syntax constructs, explain the syntax itself, common alternatives in the language, and why this particular construct was likely chosen

5. Parallelization

For large scopes (>10 files): use parallel Task agents, one per concept cluster (~5-10 files each), then merge results into a single output.

Output

Write explanations to docs/explain/ rather than inline to the conversation.

Output rules

• •Small scope (≤3 concepts): Write a single docs/explain/overview.md containing all concepts inline
• •Large scope (>3 concepts): Write docs/explain/overview.md (index with one-line summaries + links) plus one file per concept: docs/explain/<concept-slug>.md
• •Always print a short summary to the conversation listing the files written and a one-liner per concept
• •If docs/explain/ already exists, overwrite its contents (these are generated docs, not hand-written)

File format for per-concept files

# [Concept Name]
**Files:** `path/a.ext`, `path/b.ext`

[Overview paragraph]

## Key pieces
[Detailed walkthrough]

## Connections
[How this concept connects to others]

## Syntax notes (--code only)
[Language syntax explanations]

Overview index format (docs/explain/overview.md)

# Code Explanation

Generated by `/explain`. Covers [N] concepts across [M] files.

## Concepts

- **[Concept Name]** — one-line summary ([link to file](concept-slug.md))
- ...

For small scope (≤3 concepts), the overview file contains the full explanations inline instead of linking out.

Examples

Understand an auth module by concept:

/explain --all

Lists source directories and lets you pick lib/auth/. Groups the code into concepts like "Token Management," "Session Handling," and "Permission Guards" rather than explaining file-by-file, then writes results to docs/explain/.

Language syntax and architecture for unfamiliar code:

/explain --code --staged

Explains staged files with both architectural context and language-level syntax notes. Highlights non-obvious constructs like Dart extension methods or Go channel patterns, and explains why they were chosen over alternatives.

Troubleshooting

Codebase too large to explain at once

Solution: Use --all to interactively select specific directories or files instead of the entire codebase. For very large projects, focus on one module or feature area per invocation and let the parallelization handle splitting within that scope.

Unfamiliar framework or DSL

Solution: Combine --code with your scope flag so the output includes language-level syntax explanations alongside architectural context. If the framework uses heavy code generation or macros, call /research-online first to get external documentation, then run /explain --code with that context.

Notes

• •Concepts over files: always group by what the code does, not where it lives
• •Skip boilerplate: don't explain standard framework scaffolding unless --code is set
• •Be specific: reference actual function names, variable names, and line numbers
• •For --code: focus on syntax that would surprise someone from another language, not basics like if/else