thebushidocollective Explainer Skill
Create clear, insightful explanations of code, concepts, and technical decisions.
Core Principle
Clarity over completeness. An explanation is only useful if it's understood.
Name
han-core:explain - Explain code, concepts, or technical decisions in clear, understandable terms
Synopsis
/explain [arguments]
Explanation Process
1. Understand the Question
What are they really asking?
- Literal question: "What does this do?"
- Deeper question: "Why does this exist?" or "How does this work?"
- Context matters: Junior dev vs senior dev needs different explanations
2. Gather Full Context
Read before explaining:
- The code in question (obvious)
- Surrounding code (function, class, module)
- Related code (what calls it, what it calls)
- Tests (reveal intended behavior)
- Comments (capture original reasoning)
- Git history (understand evolution)
Anti-pattern: Explaining code you only partially understand
3. Structure the Explanation
Start broad, then narrow:
- One-sentence summary: What it does in plain English
- Purpose: Why it exists, what problem it solves
- High-level approach: How it solves the problem (conceptually)
- Implementation details: Specific code patterns, algorithms
- Edge cases: Unusual scenarios handled
- Related concepts: Connections to other parts of the system
4. Choose the Right Level
Match explanation to context:
For "What does this do?"
BAD: "It's a reducer function that takes state and action..."
GOOD: "This manages the shopping cart state. When you add/remove
items, it updates the cart and recalculates the total."
For "How does this work?"
BAD: "It just loops through items and sums prices."
GOOD: "It iterates through cart items, applies discounts to each,
then sums the discounted prices. Tax is calculated on the
subtotal, not individual items, to avoid rounding errors."
For "Why this approach?"
BAD: "Because it's faster."
GOOD: "We chose this over X because: (1) handles async updates
correctly, (2) prevents race conditions when multiple users
modify the cart, (3) makes testing easier. Trade-off is
slightly more complex code."
Explanation Levels
Tailor explanations based on context:
- High-level: What it does and why it exists
- Implementation: How it works internally
- Technical details: Specific algorithms, patterns, edge cases
- Historical: Why this approach was chosen over alternatives
Explanation Patterns
Code Explanation Format
## What it does
[One-sentence plain English summary]
## Purpose
[Why this code exists, what problem it solves]
## How it works
1. [High-level step 1]
2. [High-level step 2]
3. [High-level step 3]
### Key details
- [Important implementation detail 1]
- [Important implementation detail 2]
### Example
[Concrete example showing usage]
## Related
- [Link to related code/docs]
Concept Explanation Format
## [Concept Name]
[One-sentence definition]
### Why it matters
[Practical importance, when you'd use it]
### How it works
[High-level explanation without jargon]
### Example
[Concrete, relatable example]
### In our codebase
[Where we use this concept, with links]
### Common pitfalls
[What to watch out for]
Decision Explanation Format
## Decision: [What was decided]
### Context
[Situation that required a decision]
### Options considered
1. **[Option 1]**: [Brief description]
- Pros: [Key benefits]
- Cons: [Key drawbacks]
2. **[Option 2]**: [Brief description]
- Pros: [Key benefits]
- Cons: [Key drawbacks]
### Choice: [Selected option]
**Rationale:**
[Why this option was chosen over others]
### Trade-offs accepted
[What we gave up by choosing this approach]
### References
[Links to discussions, docs, related decisions]
Writing Guidelines
Be Concrete
Bad: "This uses a common design pattern for state management" Good: "This uses the Redux pattern: all state changes go through a central store via actions and reducers"
Use Analogies (When Helpful)
Example: "Think of this like a restaurant kitchen:
- Actions are customer orders
- Reducers are chefs preparing food
- Store is the completed order waiting area"
Warning: Don't force analogies. If it's clearer without, skip it.
Show, Don't Just Tell
// BAD explanation:
// "This function filters and maps the array"
// GOOD explanation:
// "This function finds all active users and formats them for display:
const displayUsers = users
.filter(u => u.status === 'active') // Only show active users
.map(u => ({ // Convert to display format
id: u.id,
name: `${u.firstName} ${u.lastName}`,
joined: formatDate(u.createdAt)
}))
Avoid Jargon (Unless Explaining Jargon)
Bad: "This leverages a memoized selector with referential equality optimization" Good: "This caches the filtered list so we don't recalculate it every render, improving performance"
Exception: When explaining what jargon means: "Memoization means caching function results so we don't recompute the same thing twice."
Common Explanation Scenarios
Explaining Error Messages
## Error: "Cannot read property 'map' of undefined"
**What happened:**
You're trying to use `.map()` on something that's `undefined`.
**Where:** [Link to line]
**Why:**
The `users` array hasn't loaded yet (async), so it's `undefined`
when the component first renders.
**Fix:**
```typescript
// Before
users.map(u => ...)
// After
{users?.map(u => ...) || <Loading />}
Why this works:
?. is optional chaining - it only calls .map() if users
exists. If not, it shows a loading state instead.
### Explaining "Why Not X?"
```markdown
## Why not use X?
**Context:** [What X is]
**Reasons we chose Y instead:**
1. **[Primary reason]**: [Explanation]
2. **[Secondary reason]**: [Explanation]
3. **[Tertiary reason]**: [Explanation]
**Trade-offs:**
Y is slower than X, but the reliability benefit outweighs the
50ms performance difference.
**When X would be better:**
If we needed real-time updates (< 100ms), X would be the right choice.
Explaining Legacy Code
## Legacy: [Module Name]
**What it does:** [Current function]
**History:**
This was written in 2019 when [context]. At the time, [justification].
**Why it looks odd today:**
Modern approaches would use [better pattern], but this works and
changing it isn't worth the risk.
**If you must modify it:**
1. [Key constraint to preserve]
2. [Another constraint]
3. Add tests first (none exist currently)
**Related:** See [modern equivalent] for new code.
Output Format
- Start with a brief summary
- Break complex explanations into sections
- Use code examples to illustrate points
- Link to relevant documentation
- Avoid jargon unless explaining jargon
Anti-Patterns
Assuming Knowledge
BAD: "This uses HOCs to inject props via connect()"
GOOD: "This connects the component to Redux, giving it access
to the store data it needs. See: [Redux docs link]"
Over-explaining Obvious Code
// Don't explain this:
const total = price * quantity // Multiplies price by quantity
// Do explain this:
const total = price * quantity * (1 - discount) * TAX_RATE
// Discount applied before tax, per accounting requirements
Vague References
BAD: "Similar to what we do in other places"
GOOD: "Similar to UserService.findActive() in services/user.ts:45"
Explaining How When Asked Why
Question: "Why do we use a Set here instead of an Array?"
Bad: "A Set is initialized with new Set() and supports .add() and .has() methods..."
Good: "A Set automatically removes duplicates. We need unique user IDs, and Set handles that for us. An Array would require manual duplicate checking."
Verification
After explaining, check:
- Does this answer the actual question asked?
- Is it understandable without reading it 3 times?
- Are technical terms explained or linked?
- Are there concrete examples?
- Does it avoid unnecessary complexity?
- Would someone new to the codebase understand this?
Examples
When the user says:
- "Explain what this function does"
- "Why are we using this pattern here?"
- "What's the difference between these two approaches?"
- "How does the authentication flow work?"
- "Explain this error message"
Integration with Other Skills
- Use code-reviewer skill when explaining code quality issues
- Use proof-of-work skill when explaining behavior (show actual output)
- Use simplicity-principles skill when explaining why simpler is better
- Reference other skills when explaining patterns they cover
Notes
- Focus on clarity over completeness
- Use analogies when helpful
- Provide context for technical decisions
- Include links to related code or docs
Remember
The best explanation is the one that's understood, not the one that's most complete.
If in doubt, start simple and add detail only when needed.