Explain Like
Explain code changes or design documents at three progressive expertise levels to ensure understanding and catch logical gaps.
When to Use
- PR/Branch Explanations: After completing work, explain changes to verify clarity
- Design Validation: After writing a design doc, explain it back to catch missing pieces
Both workflows serve knowledge transfer - helping others (or your future self) understand complex changes.
Workflow
- Determine the subject:
- Branch/PR changes? → Gather commits and diffs from git - Design document? → Read the specified design file
- Generate three explanations (all three, always):
- Beginner (0-2 years): Foundational concepts, analogies, "what" and "why" - Intermediate (5-10 years): Implementation details, patterns, trade-offs - Expert (10+ years): Architecture implications, edge cases, future considerations
- For design validation: After explaining, list any gaps or inconsistencies discovered
- Optionally save output to file for documentation (see "Saving Output" below)
Explanation Structure
For each level, follow this format:
## Beginner Level
### What Changed / What This Does
[Plain language summary - assume no domain knowledge]
### Why It Matters
[Business or user impact in simple terms]
### Key Concepts
[Define any technical terms used, with analogies where helpful]
---
## Intermediate Level
### Changes Overview
[Technical summary with specific files/components affected]
### Implementation Approach
[Patterns used, architectural decisions, how pieces fit together]
### Trade-offs
[What alternatives existed, why this approach was chosen]
---
## Expert Level
### Technical Deep Dive
[Detailed implementation, edge cases handled, performance considerations]
### Architecture Impact
[How this affects the broader system, coupling, future extensibility]
### Potential Issues
[Edge cases, failure modes, things to monitor]For Branch/PR Changes
Gather context first:
# Detect default branch (main, master, etc.)
BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
# Get commit history
git log --oneline $BASE..HEAD
# Get full diff
git diff $BASE...HEAD
# If PR exists, get PR description
gh pr view --json title,body,commitsFocus explanations on:
- What problem is being solved
- How the solution works
- Why this approach over alternatives
For Design Validation
After generating the three explanations, add a validation section:
## Validation Findings
### Gaps Identified
[List any missing requirements, undefined behaviors, or unclear sections]
### Logic Issues
[Contradictions, circular dependencies, impossible states]
### Questions Raised
[Things that became unclear when explaining at different levels]
### Recommendations
[Specific improvements to the design document]The act of explaining at beginner level often reveals assumed knowledge that should be documented. Expert-level explanation reveals edge cases and integration concerns.
Saving Output
When the user requests saving (or as part of a final review), write the explanation to a file:
- For design docs: Save alongside the design in the same specs folder as
explanation.md - For branch/PR changes: Save to
specs/<feature-name>/explanation.mdif a matching spec exists, otherwise offer to create one
Ask before saving if the user hasn't explicitly requested it.
Tone Guidelines
- Beginner: Patient, uses analogies, avoids jargon or defines it immediately
- Intermediate: Professional, assumes familiarity with common patterns
- Expert: Concise, focuses on non-obvious implications and edge cases