Explain

3. Component Explanations

• How a specific service, repository, or module works
• Integration points with other components
• Configuration and initialization

4. Pattern Explanations

• How recurring patterns are implemented across the codebase
• Best practices and conventions in use
• Comparison of different approaches used

Workflow

1. Parse the Request

Analyze the user's question to determine:

• Type of explanation needed (flow, architecture, component, pattern)
• Scope - specific file/module or cross-cutting concern
• Depth - high-level overview or detailed implementation

If the request is ambiguous, use AskUserQuestion to clarify:

• Which specific endpoint, service, or component?
• What level of detail is needed?
• Any particular aspect they're most interested in?

2. Explore the Codebase

Based on the explanation type, use appropriate exploration strategies:

For Data Flow Explanations

1. Find the entry point (API endpoint, workflow trigger, etc.)

2. Trace the call chain:

   • Request validation and parsing
   • Service layer orchestration
   • Repository/data access calls
   • External service integrations

3. Identify data transformations:

   • Input models (request specs)
   • Domain models
   • Database models/queries
   • Output models (response specs)

4. Map error handling:

   • Exception types and where they're raised
   • How they propagate and get converted
   • Final HTTP/response mapping

For Architecture Explanations

1. Understand the layer structure:

   • Explore directory structure

2. Find pattern implementations:

   • ABC/Protocol/Interface definitions in domain layer
   • Concrete implementations across packages

3. Map dependencies:

   • What depends on what
   • How interfaces are defined and implemented
   • Cross-layer communication

For Component Explanations

1. Read the component:

   • Main implementation file
   • Related specifications/models
   • Test files for usage examples

2. Find callers:

   • Who uses this component
   • How it's instantiated/injected
   • Configuration and initialization

3. Check integrations:

   • External services it calls
   • Other components it depends on
   • Events/signals it produces

3. Build the Explanation

Structure the explanation clearly:

## Overview
[2-3 sentences summarizing what this is and its purpose]

## How It Works

### [Logical Section 1]
[Explanation with file references like `src/module/file.py:123`]

### [Logical Section 2]
[Continue breaking down the topic]

## Key Files
- `path/to/file.py` - [brief description]
- `path/to/another.py` - [brief description]

## Related Concepts
- [Link to related patterns or components]
- [Suggest what to explore next]

4. Provide Actionable References

Always include:

• File paths with line numbers for key code locations
• Function/class names the developer can search for
• Related files they might want to read
• Next steps if they want to go deeper

Guidelines

Be Thorough But Focused

• Cover the topic comprehensively within scope
• Don't go off on tangents
• Stay relevant to what was asked

Use Concrete Examples

• Point to actual code, not abstract descriptions
• Include file paths and line numbers
• Show real patterns from the codebase

Make It Actionable

• The developer should know exactly where to look
• Provide enough context to navigate the code
• Suggest related areas they might explore

Begin

1. Analyze the request: $ARGUMENTS
2. Determine the type and scope of explanation needed
3. If unclear, ask clarifying questions
4. Explore the codebase systematically
5. Provide a clear, structured explanation with file references

Start by understanding what the developer wants to learn about.