explain-code

When to Use

Use this skill when the user needs to:

• Understand code they're accountable for
• Learn a new codebase or subsystem
• Build a mental model before making changes

The Explanation Structure

Present code explanations in this order:

1. Purpose (Why)

• What problem does this solve?
• Who uses it and when?
• What would break if it didn't exist?

2. High-Level Function (What)

• One-sentence summary
• Key inputs and outputs (concepts, not types)
• Where it sits in the system

3. Data Flow (Visual)

• ASCII or bullet diagram
• Start from source (hardware, user, external system)
• End with destination
• Label boundary crossings (HTTP, WebSocket, function call)

4. Step-by-Step Walkthrough (How)

• Main method/function flow
• Key state transitions
• What each step produces for the next

5. Key Design Decisions

• Why this approach? What are the tradeoffs?
• Optimizations and their conditions
• Connect back to Purpose

---

Example

Input Code

// WebSocket handler that echoes messages back
class EchoServer : public websocketpp::server<websocketpp::config::asio> {
public:
    void on_message(connection_hdl hdl, message_ptr msg) {
        std::string payload = msg->get_payload();
        
        // Log incoming
        std::cout << "Received: " << payload << std::endl;
        
        // Echo back with prefix
        std::string response = "Echo: " + payload;
        send(hdl, response, websocketpp::frame::opcode::text);
    }
};

Explanation

1. Purpose EchoServer lets clients verify their WebSocket connection works by sending any message and receiving it back. Used during development and for connection health checks.

2. High-Level Function When a message arrives, log it, prepend "Echo: ", and send it back to the same client.

3. Data Flow

Client (browser/terminal)
    │
    │ WebSocket text frame
    ▼
EchoServer::on_message()
    │
    ├──► Console log (side effect)
    │
    └──► send() with modified payload
              │
              ▼
         Client receives response