explain

name	explain
description	Explain data flows, features, and code paths in the varun.surf application with visual diagrams and step-by-step breakdowns

Explain Skill

Explain how data flows through the system, how features work, and trace code paths with clear visualizations and step-by-step breakdowns.

Instructions

When the user asks to explain something (a feature, data flow, or component), follow this process:

1. Identify What to Explain

Parse the user's request to determine:

• Data flow: How data moves from source to destination (e.g., "explain how forecasts get to the frontend")
• Feature: How a specific feature works end-to-end (e.g., "explain favorites system")
• Component: How a specific service or class works internally (e.g., "explain AggregatorService")
• Integration: How external APIs are integrated (e.g., "explain Windguru integration")

2. Gather Context

Use the following tools to understand the code:

• Glob to find relevant files
• Grep to search for specific patterns, method calls, and references
• Read to examine source code
• LSP for finding definitions, references, and call hierarchies

3. Trace the Flow

For data flows and features, trace the complete path:

Entry Point → Processing Steps → Output

Identify:

• Entry points (API endpoints, scheduled tasks, user actions)
• Service layer processing
• Data transformations
• External API calls
• Caching layers
• Response formatting

4. Create Visual Diagrams

Use ASCII diagrams to visualize:

For data flows:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Source    │────▶│  Transform  │────▶│ Destination │
└─────────────┘     └─────────────┘     └─────────────┘

For component interactions:

            ┌──────────────────┐
            │   Controller     │
            └────────┬─────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │Service A│  │Service B│  │Service C│
   └─────────┘  └─────────┘  └─────────┘

For state transitions:

[State A] ──(action)──▶ [State B] ──(action)──▶ [State C]

5. Provide Step-by-Step Breakdown

Structure the explanation as:

1. Overview: High-level summary (2-3 sentences)
2. Entry Point: Where the flow begins
3. Step-by-Step Flow: Each processing step with file:line references
4. Key Code Snippets: Important code sections (keep concise)
5. Data Transformations: How data shape changes
6. External Dependencies: APIs, databases, caches involved
7. Error Handling: How errors are managed
8. Related Components: Other parts of the system that interact

6. Include Code References

Always include file paths with line numbers for easy navigation:

• src/main/java/.../SpotsController.java:45 - endpoint definition
• src/main/java/.../AggregatorService.java:120 - data aggregation

Output Format

# Explaining: [Topic]

## Overview
[2-3 sentence summary]

## Visual Diagram
[ASCII diagram showing the flow]

## Step-by-Step Flow

### 1. [Step Name]
**File**: `path/to/file.java:line`

[Description of what happens]

```java
// Key code snippet (if helpful)

2. [Next Step]

...

Data Transformations

Stage	Data Shape	Example
Input	Type	{...}
Output	Type	{...}

Key Files Involved

• path/to/file1.java - [purpose]
• path/to/file2.java - [purpose]

Related Features

• [Feature 1]: [brief relation]
• [Feature 2]: [brief relation]

## Example Topics

Common explanations users might request:

### Data Flows
- "How do forecasts get from Windguru to the frontend?"
- "How are live conditions fetched and displayed?"
- "How does the caching system work?"
- "How does the spot data flow from JSON to API response?"

### Features
- "How does the favorites system work?"
- "How does country filtering work?"
- "How does the search functionality work?"
- "How does theme switching work?"
- "How does the kite size calculator work?"

### Components
- "How does AggregatorService orchestrate data fetching?"
- "How do the FetchCurrentConditionsStrategy implementations work?"
- "How does the ForecastService parse Windguru data?"
- "How does the frontend manage state?"

### Integrations
- "How is Windguru integrated?"
- "How is Google Maps integration working?"
- "How does the AI analysis feature work?"

## Notes

- Keep explanations concise but complete
- Use diagrams to make complex flows understandable
- Always include file:line references for code navigation
- Focus on the specific topic, don't over-explain tangential concerns
- If the topic is ambiguous, ask clarifying questions
- Reference CLAUDE.md, docs/BACKEND.md, and docs/FRONTEND.md for architectural context