explain-code

Input Handling

1. Ask: "What code would you like me to explain?"
2. Suggest: "I can explain a specific file, function, or concept."

Anti-Hallucination Rules

• Read first, explain second: Never explain code without reading it
• Verify references: Check that files/functions exist before citing them
• Trace actual execution: Don't assume what code does - trace it
• Distinguish fact from inference: Say "the code shows..." vs "this likely..."
• Admit gaps: If you can't find something, say "I couldn't locate..."

Project Context

Explanation Structure

1. Purpose: What does this code accomplish? (1-2 sentences)
2. How It Works: Step-by-step walkthrough of the logic
3. Key Concepts: Patterns, algorithms, or techniques used
4. Dependencies: What does this code depend on? What depends on it?
5. Side Effects: State changes, API calls, file writes, events emitted

Guidelines

• Read before explaining: Trace the actual execution, don't guess
• Adjust depth: Match complexity of explanation to complexity of code
• Use diagrams: ASCII flowcharts for complex control flow
• Highlight gotchas: Non-obvious behavior, edge cases, assumptions
• Reference context: Link to related files, functions, or documentation
• Distinguish fact from inference: Be clear about what you traced vs inferred

What NOT to Do

• Explain line-by-line for simple code (explain concepts instead)
• Make assumptions about behavior without tracing
• Skip over "obvious" parts that may not be obvious to the reader
• Ignore error handling paths

Process

1. Read CLAUDE.md for project context
2. Read the code thoroughly before explaining
3. Trace execution flow, including error paths
4. Identify key abstractions and data structures
5. Explain from high-level purpose to low-level details
6. Note assumptions the code makes
7. Flag anything unclear or potentially buggy

Output Format

## [Function/File Name]

**Purpose**: [1-2 sentence summary]

**How it works**:
1. [Step 1 with file:line reference]
2. [Step 2]
...

**Key concepts**: [Patterns used, why they matter]

**Dependencies**: [What this calls/uses]

**Callers**: [What uses this]

**Side effects**: [State changes, I/O]

**Gotchas**: [Non-obvious behavior, edge cases]