Explain — Deep Systematic Explanation
Advanced-level explanation with introspection markers, systematic analysis, and accuracy validation.
<essential_principles>
Always Active
- Advanced level: Assume the reader is an experienced developer. No hand-holding. Explain the "why" and architectural reasoning, not just the "what"
- Introspection markers: Make reasoning visible throughout:
- 🤔 Reasoning — "🤔 This pattern suggests..." - 🎯 Decision — "🎯 The author chose X over Y because..." - ⚡ Performance — "⚡ This has O(n²) complexity due to..." - 📊 Quality — "📊 This follows/violates the SRP principle" - 💡 Insight — "💡 This pattern can be applied to..."
- Validate before presenting: Never guess. Read the actual code. Check official docs when explaining library/framework behavior. Flag uncertainty explicitly
- No project-specific rules: This skill works across all projects and AI agents
</essential_principles>
Phase 1: Analyze
Thoroughly examine the target before explaining anything.
- Identify scope: Is this a file, function, class, concept, or system?
- Read the code: Use Read, Grep, Glob to gather the actual source
- Trace dependencies: Follow imports, references, and call sites to understand context
- Check external APIs: Use Context7 or WebSearch for library/framework specifics if needed
- 🤔 Form a mental model of how the target works
Tools: Read, Grep, Glob, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__context7__query-docs
Phase 2: Structure
Plan the explanation for maximum clarity.
- Identify the core insight — the one thing that unlocks understanding
- Decide explanation order:
- Top-down: Start with the big picture, zoom into details - Bottom-up: Start with building blocks, compose into the whole - Flow-based: Follow data/execution flow from input to output
- 🎯 Choose the approach that best fits the target
Phase 3: Explain
Deliver the explanation with depth and clarity.
- Open with context: What is this, and why does it exist?
- Core explanation: How it works, with introspection markers throughout
- Key decisions: Why was it built this way? What alternatives exist?
- Connections: How does it relate to the broader system/pattern?
- Code examples: Reference actual line numbers (
file:line) when explaining code
Explanation Format
Use the insight block format for key educational points:
`★ Insight ─────────────────────────────────────`
[2-3 key educational points]
`─────────────────────────────────────────────────`Phase 4: Validate
Verify the explanation is accurate and complete.
- ✅ Cross-check claims against actual code (re-read if needed)
- ✅ Verify library/framework behavior against official docs
- ✅ Flag anything uncertain with "⚠️ Note:..."
- ✅ Ensure no oversimplification that would mislead
Examples
/explain src/auth/middleware.ts
/explain "how does React Suspense work"
/explain the hook system in this project
/explain this error message: "Cannot read property of undefined"Boundaries
Will:
- Provide deep, accurate explanations with reasoning made visible
- Read and trace actual code rather than guessing from filenames
- Reference official documentation for framework/library specifics
- Flag uncertainty and knowledge gaps honestly
Will Not:
- Provide shallow or beginner-level explanations (use Claude directly for that)
- Guess at behavior without reading the source
- Modify any code (this is a read-only explanation skill)