SuperClaude/.claude/commands/explain.md

/explain - Provide detailed technical explanations

Legend

Symbol	Meaning		Abbrev	Meaning
→	leads to		cfg	configuration
&	and/with		impl	implementation
w/	with		perf	performance
@	at/located		ops	operations
>	greater than		val	validation
∀	for all/every		req	requirements
∃	exists/there is		deps	dependencies
∴	therefore		env	environment
∵	because		db	database
≡	equivalent		api	interface
≈	approximately		docs	documentation
📁	directory/path		std	standard
🔢	number/count		def	default
📝	text/string		ctx	context
⚙	setting/config		err	error
🎛	control/flags		exec	execution
🔧	configuration		qual	quality
📋	group/category		rec	recovery
🚨	critical/urgent		sev	severity
⚠	warning/caution		resp	response
🔄	retry/recovery		esc	escalation
✅	success/fixed		tok	token
❌	failure/error		opt	optimization
ℹ	information		UX	user experience
⚡	fast/quick		UI	user interface
🐌	slow/delayed		C	critical
✨	complete/done		H	high
📖	read operation		M	medium
✏	edit operation		L	low
🗑	delete operation

Purpose

Provide comprehensive explanations of concepts, code, or systems specified in $ARGUMENTS with appropriate depth and visual aids.

Syntax

/explain [flags] [concept/topic]

Universal Flags

--plan: "Show execution plan before running" --uc: "UltraCompressed mode (~70% token reduction)" --ultracompressed: "Alias for --uc" --think: "Multi-file analysis w/ context (4K tokens)" --think-hard: "Deep architectural analysis (10K tokens)" --ultrathink: "Critical system redesign (32K tokens)" --c7: "Enable Context7→library documentation lookup" --seq: "Enable Sequential→complex analysis & thinking" --magic: "Enable Magic→UI component generation" --pup: "Enable Puppeteer→browser automation & testing" --all-mcp: "Enable all MCP servers" --no-mcp: "Disable all MCP servers (native tools only)" --no-c7: "Disable Context7 specifically" --no-seq: "Disable Sequential thinking specifically" --no-magic: "Disable Magic UI builder specifically" --no-pup: "Disable Puppeteer specifically"

Command-Specific Flags

Explanation Depth:

• --depth eli5: Simple analogies, avoid jargon, focus on core concepts
• --depth beginner: Cover basics with step-by-step guidance and simple examples
• --depth intermediate: Technical details, best practices, common patterns
• --depth expert: Deep implementation details, edge cases, performance considerations

Content Enhancement:

• --visual: Create diagrams using Mermaid syntax, ASCII art, flowcharts
• --examples: Include practical, runnable code examples
• --comparisons: Add comparison tables and pros/cons analysis
• --interactive: Create interactive explanations with guided discovery

Research Integration:

• --c7: Fetch official library/framework documentation
• --seq: Step-by-step concept breakdown with complex analysis
• --no-mcp: Explain using only codebase context

Output Format:

• --structured: Organize explanation with clear sections and hierarchy
• --quick: Concise explanation focusing on key points
• --comprehensive: Complete explanation covering all aspects

Examples

• /explain --c7 "React hooks" --visual --think → React hooks with diagrams and connections
• /explain --seq "OAuth flow" --depth expert --think-hard → Deep OAuth analysis with security implications
• /explain --depth eli5 "async/await" --examples → Simple async explanation with examples
• /explain --visual --comparisons "REST vs GraphQL" → API comparison with diagrams
• /explain --comprehensive --c7 "Docker containers" → Complete Docker explanation with docs

Explanation Structure

1. High-Level Overview:

• Start with the big picture
• Define the problem or concept
• Explain why it matters
• Set context and scope

2. Core Components:

• Break down into logical parts
• Explain each component clearly
• Show relationships and dependencies
• Use appropriate technical depth

3. Practical Application:

• Provide concrete examples
• Show real-world usage
• Include code snippets
• Demonstrate best practices

4. Advanced Concepts:

• Cover edge cases and gotchas
• Explain performance implications
• Discuss alternatives and trade-offs
• Address common misconceptions

Content Types

Technical Concepts:

• Explain "what" before "how"
• Connect to familiar concepts
• Build understanding incrementally
• Use analogies and metaphors
• Address common misconceptions

Code Explanations:

• Walk through logic step by step
• Explain design decisions and rationale
• Highlight important patterns
• Point out potential pitfalls
• Show alternative approaches

System Architecture:

• Start with overall design
• Explain component interactions
• Show data flow and processes
• Discuss scalability and performance
• Cover security considerations

Framework/Library Usage:

• Explain core concepts first
• Show common usage patterns
• Provide working examples
• Explain configuration options
• Cover troubleshooting tips

Visual Aids (--visual)

Diagram Types:

• Mermaid Diagrams: Flowcharts, sequence diagrams, class diagrams
• ASCII Art: Simple visualizations and layouts
• Process Flows: Step-by-step workflow diagrams
• Architecture Diagrams: System component relationships

When to Use Visuals:

• Complex processes or workflows
• System architecture explanations
• Data flow and transformations
• Relationship mapping
• Timeline or sequence explanations

Research Requirements

Authoritative Sources:

• Official documentation via --c7
• Framework guides and best practices
• Industry standards and specifications
• Expert opinions and case studies

Verification Standards:

• Never explain without verification
• Always cite authoritative sources
• Test code examples before including
• Validate against current versions
• Include source references in explanations

UltraCompressed Mode (--uc)

Compression Rules:

• ~70% token reduction from standard explanations
• Generate legend for symbols/abbreviations
• Use telegram-style formatting
• Structure: lists > paragraphs, tables > prose
• Remove articles, conjunctions, fillers
• Focus on essential information only

Example Transformation:

• Standard: "The function takes three parameters and returns a boolean value"
• Compressed: "fn takes 3 params→bool"

Deliverables

• Clear Explanations: Appropriate depth level with structured content
• Working Examples: Tested, runnable code snippets
• Visual Aids: Diagrams, charts, and illustrations (if requested)
• Learning Resources: Curated resources for further study
• Source References: Comprehensive citations and links

Output Locations

• Explanations: .claudedocs/summaries/explanation-{topic}-{timestamp}.md
• Learning Resources: .claudedocs/reports/learning-resources-{timestamp}.md
• Code Examples: Embedded in explanation files

Research Requirements

External_Library_Research:

• Identify library/framework mentioned
• Context7 lookup for official documentation
• Verify API patterns and examples
• Check version compatibility
• Document findings in implementation Pattern_Research:
• Search existing codebase for similar patterns
• Magic component search if UI-related
• WebSearch for official documentation
• Validate approach with Sequential thinking
• Document pattern choice rationale API_Integration_Research:
• Official documentation lookup
• Authentication requirements
• Rate limiting and error handling
• SDK availability and examples
• Integration testing approach

Report Notifications

📄 Analysis report saved to: {path} 📊 Metrics updated: {path} 📋 Summary saved to: {path} 💾 Checkpoint created: {path} 📚 Documentation created: {path} 📁 Created directory: {path} ✅ {operation} completed successfully ❌ {operation} failed: {reason} ⚠ {operation} completed w/ warnings

Best Practices

Effective Explanations:

• Start simple, build complexity gradually
• Use concrete examples and analogies
• Address the audience's experience level
• Anticipate and answer common questions
• Provide multiple perspectives when helpful

Quality Standards:

• Verify all technical information
• Test all code examples
• Keep explanations current and accurate
• Use clear, precise language
• Structure content logically

Troubleshooting

• Complex Topics: Use --seq --think-hard for step-by-step breakdown
• Framework Questions: Combine --c7 --examples for comprehensive coverage
• Beginner Audiences: Use --depth eli5 --visual --examples
• Expert Deep Dives: Apply --depth expert --comprehensive --ultrathink

Success Messages

✅ {operation} completed successfully 📝 Created: {file_path} ✏ Updated: {file_path} ✨ Task completed: {task_title}