---
name: explain-code
description: Explain code functionality in detail.
---

# Analyze and Explain Code Functionality

## Available Tools

- **Playwright CLI** (`playwright-cli`): Use to retrieve external documentation, browse web content, and extract data from documentation sites, forums, and GitHub repositories — especially useful for understanding third-party dependencies and their APIs. Invoke via the `/playwright-cli` skill or run `npx playwright-cli` commands directly.

<EXTREMELY_IMPORTANT>
- PREFER to use the playwright-cli (refer to playwright-cli skill) OVER web fetch/search tools
  - ALWAYS load the playwright-cli skill before usage with the Skill tool.
  - ALWAYS ASSUME you have the playwright-cli tool installed (if the `playwright-cli` command fails, fallback to `npx playwright-cli`).
</EXTREMELY_IMPORTANT>

### Web Fetch Strategy (token-efficient order)

When you need external documentation about a library, framework, or API, use the **playwright-cli** skill (or `curl`) and apply these techniques in order — stop as soon as you have what you need:

1. **Check `/llms.txt` first** — Many modern docs sites publish an AI-friendly index at `/llms.txt` (spec: [llmstxt.org](https://llmstxt.org/llms.txt)). Try `curl https://<site>/llms.txt` before anything else; it often links directly to the most relevant pages in plain text.
2. **Request Markdown via `Accept: text/markdown`** — For any HTML page, try `curl <url> -H "Accept: text/markdown"` first. Sites behind Cloudflare with [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) will return pre-converted Markdown (look for `content-type: text/markdown` and the `x-markdown-tokens` header), which is far cheaper than raw HTML.
3. **Fall back to HTML parsing** — If neither above yields usable content, navigate the page with `playwright-cli` to extract the rendered DOM, or `curl` the raw HTML and parse locally.

**Persist useful findings to `research/web/`:** When you fetch a document worth keeping for future sessions (API references, SDK guides, troubleshooting docs), save it to `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` with a short header noting the source URL and fetch date. Check this directory first before re-fetching.

## Instructions

Follow this systematic approach to explain code: **$ARGUMENTS**

1. **Code Context Analysis**
    - Identify the programming language and framework
    - Understand the broader context and purpose of the code
    - Identify the file location and its role in the project
    - Review related imports, dependencies, and configurations

2. **High-Level Overview**
    - Provide a summary of what the code does
    - Explain the main purpose and functionality
    - Identify the problem the code is solving
    - Describe how it fits into the larger system

3. **Code Structure Breakdown**
    - Break down the code into logical sections
    - Identify classes, functions, and methods
    - Explain the overall architecture and design patterns
    - Map out data flow and control flow

4. **Line-by-Line Analysis**
    - Explain complex or non-obvious lines of code
    - Describe variable declarations and their purposes
    - Explain function calls and their parameters
    - Clarify conditional logic and loops

5. **Algorithm and Logic Explanation**
    - Describe the algorithm or approach being used
    - Explain the logic behind complex calculations
    - Break down nested conditions and loops
    - Clarify recursive or asynchronous operations

6. **Data Structures and Types**
    - Explain data types and structures being used
    - Describe how data is transformed or processed
    - Explain object relationships and hierarchies
    - Clarify input and output formats

7. **Framework and Library Usage**
    - Explain framework-specific patterns and conventions
    - Describe library functions and their purposes
    - Explain API calls and their expected responses
    - Clarify configuration and setup code
    - Use the **playwright-cli** skill (following the Web Fetch Strategy above) to look up external library documentation when needed

8. **Error Handling and Edge Cases**
    - Explain error handling mechanisms
    - Describe exception handling and recovery
    - Identify edge cases being handled
    - Explain validation and defensive programming

9. **Performance Considerations**
    - Identify performance-critical sections
    - Explain optimization techniques being used
    - Describe complexity and scalability implications
    - Point out potential bottlenecks or inefficiencies

10. **Security Implications**
    - Identify security-related code sections
    - Explain authentication and authorization logic
    - Describe input validation and sanitization
    - Point out potential security vulnerabilities

11. **Testing and Debugging**
    - Explain how the code can be tested
    - Identify debugging points and logging
    - Describe mock data or test scenarios
    - Explain test helpers and utilities
    - Use `playwright-cli` to reproduce browser interactions and validate frontend behavior when applicable

12. **Dependencies and Integrations**
    - Explain external service integrations
    - Describe database operations and queries
    - Explain API interactions and protocols
    - Clarify third-party library usage

**Explanation Format Examples:**

**For Complex Algorithms:**

```
This function implements a depth-first search algorithm:

1. Line 1-3: Initialize a stack with the starting node and a visited set
2. Line 4-8: Main loop - continue until stack is empty
3. Line 9-11: Pop a node and check if it's the target
4. Line 12-15: Add unvisited neighbors to the stack
5. Line 16: Return null if target not found

Time Complexity: O(V + E) where V is vertices and E is edges
Space Complexity: O(V) for the visited set and stack
```

**For API Integration Code:**

```
This code handles user authentication with a third-party service:

1. Extract credentials from request headers
2. Validate credential format and required fields
3. Make API call to authentication service
4. Handle response and extract user data
5. Create session token and set cookies
6. Return user profile or error response

Error Handling: Catches network errors, invalid credentials, and service unavailability
Security: Uses HTTPS, validates inputs, and sanitizes responses
```

**For Database Operations:**

```
This function performs a complex database query with joins:

1. Build base query with primary table
2. Add LEFT JOIN for related user data
3. Apply WHERE conditions for filtering
4. Add ORDER BY for consistent sorting
5. Implement pagination with LIMIT/OFFSET
6. Execute query and handle potential errors
7. Transform raw results into domain objects

Performance Notes: Uses indexes on filtered columns, implements connection pooling
```

13. **Common Patterns and Idioms**
    - Identify language-specific patterns and idioms
    - Explain design patterns being implemented
    - Describe architectural patterns in use
    - Clarify naming conventions and code style

14. **Potential Improvements**
    - Suggest code improvements and optimizations
    - Identify possible refactoring opportunities
    - Point out maintainability concerns
    - Recommend best practices and standards

15. **Related Code and Context**
    - Reference related functions and classes
    - Explain how this code interacts with other components
    - Describe the calling context and usage patterns
    - Point to relevant documentation and resources

16. **Debugging and Troubleshooting**
    - Explain how to debug issues in this code
    - Identify common failure points
    - Describe logging and monitoring approaches
    - Suggest testing strategies

**Language-Specific Considerations:**

**JavaScript/TypeScript:**

- Explain async/await and Promise handling
- Describe closure and scope behavior
- Clarify this binding and arrow functions
- Explain event handling and callbacks

**Python:**

- Explain list comprehensions and generators
- Describe decorator usage and purpose
- Clarify context managers and with statements
- Explain class inheritance and method resolution

**Java:**

- Explain generics and type parameters
- Describe annotation usage and processing
- Clarify stream operations and lambda expressions
- Explain exception hierarchy and handling

**C#:**

- Explain LINQ queries and expressions
- Describe async/await and Task handling
- Clarify delegate and event usage
- Explain nullable reference types

**Go:**

- Explain goroutines and channel usage
- Describe interface implementation
- Clarify error handling patterns
- Explain package structure and imports

**Rust:**

- Explain ownership and borrowing
- Describe lifetime annotations
- Clarify pattern matching and Option/Result types
- Explain trait implementations

Remember to:

- Use clear, non-technical language when possible
- Provide examples and analogies for complex concepts
- Structure explanations logically from high-level to detailed
- Include visual diagrams or flowcharts when helpful
- Tailor the explanation level to the intended audience
- Use the **playwright-cli** skill (following the Web Fetch Strategy above) to look up external library documentation when encountering unfamiliar dependencies, and for live browser inspection when static code analysis is not enough
