Initial commit: Fresh start with current state

.claude/commands/explain.md

@@ -0,0 +1,152 @@
+---
+description: Explain code in detail - how it works, patterns used, and key concepts
+allowed-tools: Read(*), Grep(*), Glob(*), Bash(git log:*)
+argument-hint: [file-or-selection]
+---
+
+# Explain Command
+
+Provide detailed, educational explanations of code.
+
+## Technology Adaptation
+
+**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)
+
+Consult CLAUDE.md for:
+- **Language**: To explain syntax and language-specific features
+- **Frameworks**: To identify framework patterns and conventions
+- **Project Patterns**: To explain project-specific architectures
+
+## Instructions
+
+1. **Identify Target**
+   - If $ARGUMENTS provided: Explain that file/code
+   - If user has selection: Explain selected code
+   - Otherwise: Ask what needs explanation
+
+2. **Analyze Code**
+   - Read CLAUDE.md to understand project context
+   - Use serena MCP to understand code structure
+   - Identify patterns, algorithms, and design choices
+   - Understand dependencies and relationships
+
+3. **Provide Explanation**
+   Include these sections:
+   - **Purpose**: What this code does (high-level)
+   - **How It Works**: Step-by-step breakdown
+   - **Key Concepts**: Patterns, algorithms, principles used
+   - **Dependencies**: What it relies on
+   - **Important Details**: Edge cases, gotchas, considerations
+   - **In Context**: How it fits in the larger system
+
+4. **Adapt Explanation Level**
+   - Use clear, educational language
+   - Explain technical terms when first used
+   - Provide examples where helpful
+   - Reference CLAUDE.md patterns when relevant
+
+## MCP Server Usage
+
+### Serena MCP
+
+**Code Navigation**:
+- `find_symbol` - Locate symbols to explain
+- `find_referencing_symbols` - Understand usage and relationships
+- `get_symbols_overview` - Get file structure and organization
+- `search_for_pattern` - Find related patterns
+
+**Persistent Memory** (stored in `.serena/memories/`):
+- Use `write_memory` to store complex explanations for future reference:
+  - "explanation-algorithm-[name]"
+  - "explanation-pattern-[pattern-name]"
+  - "explanation-architecture-[component]"
+- Use `read_memory` to recall past explanations of related code
+- Use `list_memories` to find previous explanations
+
+### Memory MCP (Knowledge Graph)
+
+**Temporary Context** (in-memory, cleared after session):
+- Use `create_entities` for code elements being explained
+- Use `create_relations` to map relationships between components
+- Use `add_observations` to document understanding
+
+**Note**: After explanation, store reusable patterns in Serena memory.
+
+### Context7 MCP
+- Use `get-library-docs` for framework/library documentation and official explanations
+
+## Output Format
+
+```markdown
+## Explanation: [Code/File Name]
+
+### Purpose
+[What this code accomplishes and why it exists]
+
+### How It Works
+
+#### Step 1: [High-level step]
+[Detailed explanation]
+
+```[language]
+[Relevant code snippet]
+```
+
+#### Step 2: [Next step]
+[Explanation]
+
+### Key Concepts
+
+#### [Concept 1]: [Name]
+[Explanation of pattern/algorithm/principle]
+
+#### [Concept 2]: [Name]
+[Explanation]
+
+### Dependencies
+- **[Dependency 1]**: [What it provides and why needed]
+- **[Dependency 2]**: [What it provides and why needed]
+
+### Important Details
+- **[Detail 1]**: [Edge case or consideration]
+- **[Detail 2]**: [Gotcha or important note]
+
+### In the Larger System
+[How this fits into the project architecture from CLAUDE.md]
+
+### Related Code
+[Links to related files or functions]
+
+### Further Reading
+[References to documentation or patterns]
+```
+
+## Example Output Scenarios
+
+### For a Function
+- Explain algorithm and complexity
+- Show input/output examples
+- Highlight edge cases
+- Explain why this approach was chosen
+
+### For a Class
+- Explain responsibility and role
+- Show key methods and their purposes
+- Explain relationships with other classes
+- Highlight design patterns used
+
+### For a Module
+- Explain module's purpose in architecture
+- Show public API and how to use it
+- Explain internal organization
+- Show integration points
+
+## Guidelines
+
+- Start with high-level understanding, then dive into details
+- Use analogies when helpful
+- Explain "why" not just "what"
+- Reference CLAUDE.md patterns
+- Be educational but concise
+- Assume reader has basic programming knowledge
+- Adapt detail level based on code complexity