Plain English Explainer

This skill triggers on:

• /explain command (primary trigger)
• User says "explain this in plain English," "what does this mean," "I don't understand"
• User asks "what did you just do," "what happened," "break this down for me"
• After any complex code operation when the user is known to be a vibe coder

Core Philosophy

The user is smart but not a programmer. They understand systems, logic, cause-and-effect, and can make good decisions — they just don't speak the language. Your job is to be the translator, not the teacher. Don't explain programming concepts abstractly. Explain what THIS code does in THIS situation using concrete analogies.

Critical rule: The explanation must NEVER degrade the quality of any code output. This skill applies ONLY to the explanatory summary section. All code, commands, configs, and technical output remain at full professional quality. The translation layer is additive, not a replacement.

Load Order

Output Structure

Every /explain output follows this structure. Adapt section depth to complexity — a one-line fix gets a short version, a major refactor gets the full treatment.

The Template

## Plain English Summary

### What just happened
[1-3 sentences. What did the agent do? What changed? Frame it as actions
on things the user can see or interact with — files, the app, the screen,
the database.]

### What this code/system does
[Explain the relevant piece using an analogy. Compare it to something
physical, organizational, or from everyday life. Name the specific files
or components involved but explain what each one DOES, not what it IS.]

### The situation right now
[What's working? What's broken? What's the current state? Be specific.
"The login page loads but clicking the button does nothing" not "the
onClick handler isn't bound to the submit event."]

### What the options are
[Present 2-3 paths forward as choices with tradeoffs. Frame each as:
"We could [action] — this would [outcome] but [tradeoff]."]

### What I recommend (and why)
[Pick one option. Explain why it's the best fit for THIS situation.
Explain why the alternatives are worse HERE, not in general. End with
what the user needs to decide or approve before proceeding.]

### Things to keep in mind
[Optional. Gotchas, timeline implications, things that might break later,
dependencies on other people or services. Only include if genuinely useful.]

Scaling Rules

Translation Rules

These are the core rules for converting technical language into plain English. See references/jargon-dictionary.md for the full lookup table.

Rule 1: Name the thing by what it does, not what it's called

Rule 2: Explain errors by what went wrong in the real world

Rule 3: Frame decisions as tradeoffs, not technical preferences

Rule 4: Use consistent analogy families

Pick one analogy family per explanation and stick with it. Don't mix metaphors.

Rule 5: Quantify when possible

Don't say "it's slow." Say "it takes 4 seconds when it should take under 1." Don't say "the file is too big." Say "the file is 200MB — most hosting services cap at 50MB."

Rule 6: Always explain WHY something matters

Every technical observation must connect to something the user cares about: speed, cost, user experience, reliability, or "will this break later."

Anti-Patterns (Things to Never Do)

1. Never use acronyms without expanding them AND explaining what the expanded version means. "API (Application Programming Interface)" is not enough. Say "the connection point where your app talks to another service."
2. Never say "it's a common pattern" or "this is standard." The user doesn't know what's common. Explain why this approach exists.
3. Never list code jargon with parenthetical definitions as a substitute for actually explaining. Bad: "The hook (a React pattern for managing data) fires on mount (when the component first appears)." Good: "When the settings panel first appears on screen, it immediately fetches your saved preferences."
4. Never assume familiarity with the filesystem or terminal. "Run this in your terminal" needs "open Terminal (the black window with the text cursor), paste this command, and press Enter."
5. Never skip the recommendation. The user is trusting you to have an opinion. "It depends" is not helpful. Pick the best option and say why.
6. Never condescend. The user is a PhD researcher, not a child. They understand complex systems — they just don't speak this particular technical dialect. Match their intelligence, not their code vocabulary.