explain-code

name	explain-code
mode	agent
description	Explain a code element, file, or line range with diagrams and architectural context
argument-hint	[function-name|class-name|file-path|line-range]

Explain Code

Purpose

Provides comprehensive explanations of code segments, functions, classes, or entire files. Combines natural language explanations with visual diagrams to help developers understand complex code quickly and thoroughly.

Parameters

Target (Required)

• [function-name] - Specific function to explain
• [class-name] - Entire class explanation
• [file-path] - Explain entire file
• [line-range] - Explain specific lines (e.g., src/utils/helpers.js:45-78)
• current-selection - Explain currently selected or pasted code

The skill automatically:

• Includes visual diagrams (flowcharts, sequence diagrams, class diagrams)
• Uses intermediate complexity level (technical but accessible)
• Provides full context (includes dependencies and related components)
• Saves explanations to .code-captain/explanations/ for future reference

Examples

/explain-code calculateUserDiscount
/explain-code PaymentProcessor
/explain-code src/auth/AuthService.js
/explain-code "src/utils/helpers.js:45-78"
/explain-code current-selection

Process

Step 1: Locate Target Code

1. If a function/class name is given, use Grep to find its definition in the codebase
2. If a file path is given, use Read to load the file
3. If a line range is given, use Read with offset/limit to load just those lines
4. If current-selection, ask the user to paste the code if not already visible

Step 2: Gather Context

1. Use Read to load the file containing the target (if not already loaded)
2. Use Grep to find callers, dependencies, and related components
3. Use Glob to identify related files (tests, types, interfaces)
4. Build a mental model of where this code fits in the system

Step 3: Generate Explanation

Produce a comprehensive explanation covering:

📋 Function/Class Overview

• Purpose: What this code does
• Parameters: Input expectations and types
• Return Value: What it outputs
• Key Logic: Step-by-step breakdown

🔄 Execution Flow

• Mermaid flowchart showing decision paths
• Decision points and branches
• Error handling paths
• Performance characteristics

🏗️ Architecture Context

• Where this fits in the system
• Dependencies and related components
• Design patterns used
• Integration points

⚡ Technical Details

• Time complexity (if relevant)
• Memory usage considerations
• Potential issues or gotchas
• Optimization opportunities

Step 4: Save Explanation

1. Get current date:

   date +%Y-%m-%d
   

2. Create file: .code-captain/explanations/[DATE]-[target-name].md

Saved Format:

# Code Explanation: [Target Name]

_Generated on [DATE]_

## Overview

[Natural language summary]

## Execution Flow

```mermaid
[Generated diagram]

Detailed Breakdown

[Step-by-step explanation]

Architecture Context

[How it fits in the system]

Usage Examples

[Code examples]

Related Components

[Links to other explanations or files]

---

Generated by Code Captain on [timestamp]

### Step 5: Present Output

Display the full explanation in chat, then confirm where the file was saved.

## Output Characteristics

All explanations use a consistent intermediate technical level:

- **Technical but accessible**: Explains how the code works with some optimization details
- **Full context**: Always includes related functions, dependencies, and architectural context
- **Visual diagrams**: Every explanation includes appropriate Mermaid flowcharts, sequence diagrams, or class diagrams
- **Comprehensive coverage**: Shows how the code fits in the entire system

## File Organization

.code-captain/ └── explanations/ ├── 2024-01-15-AuthenticationFlow.md ├── 2024-01-16-PaymentProcessor.md └── 2024-01-17-SearchAlgorithm.md

Files are named using the format: `[YYYY-MM-DD]-[target-name].md`

## Diagram Types Generated

### Flowcharts
- Control flow through functions
- Decision trees for complex logic
- Error handling paths

### Sequence Diagrams
- Function call sequences
- API interaction flows
- Database transaction flows

### Class Diagrams
- Object relationships
- Inheritance hierarchies
- Dependency structures

## Error Handling

- **Code not found**: Report "Could not locate [target]. Please check the path/name."
- **Too complex**: Suggest breaking into smaller explanations
- **Limited context**: Note that some context may be missing and explain what was found
- **Diagram fails**: Provide text-based flow description as fallback