Translate technical code output, error messages, architectural decisions, and development workflows into structured plain-English explanations for non-proficient coders. Triggered by /explain command. Also use this skill whenever the user says "explain this," "what does this mean," "I don't understand," "break this down," "what did you just do," "what happened," or any variant asking for clarification of technical output. Use it proactively when the user is a known vibe coder and the output involves complex pipelines, architecture, or multi-step debugging. Produces a markdown summary covering what happened, what the code does, what went wrong, what the options are, and what the agent recommends, all without code jargon.
Turn code output into something a human can actually read.
This skill improves over time. MUST read FEEDBACK.md before every use to apply lessons from prior runs.
Cycle:
FEEDBACK.md for prior entries on the same issue.FEEDBACK.md with category tag and date.This skill triggers on:
/explain command (primary trigger)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.
| Resource | When |
|---|---|
FEEDBACK.md | Always — before every use |
references/jargon-dictionary.md | Always — the translation reference |
references/explanation-templates.md | When structuring the output |
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.
## 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.]
| Complexity | Sections to include |
|---|---|
| Simple fix (typo, config tweak, one-liner) | "What just happened" + "The situation right now" (2-3 sentences total) |
| Medium task (bug fix, feature addition, refactor) | All sections, moderate depth |
| Complex/architectural (migration, new system, multi-file overhaul) | All sections, full depth, multiple analogies |
These are the core rules for converting technical language into plain English. See references/jargon-dictionary.md for the full lookup table.
| Instead of... | Say... |
|---|---|
| "The API endpoint" | "The part of the server that handles login requests" |
| "The React component" | "The piece of code that draws the settings panel" |
| "The middleware" | "The checkpoint that every request passes through before reaching the main code" |
| "The ORM" | "The translator that converts your app's data requests into database language" |
| "The webhook" | "An automatic notification that fires when something happens on the other service" |
| Instead of... | Say... |
|---|---|
| "TypeError: Cannot read properties of undefined" | "The code tried to use a piece of data that doesn't exist yet — like opening a filing cabinet drawer that was never installed" |
| "CORS error" | "The browser blocked the request because the app and the server are on different addresses, and the server hasn't said 'yes, I trust that address'" |
| "Race condition" | "Two things tried to happen at the same time and stepped on each other — like two people trying to edit the same cell in a spreadsheet simultaneously" |
| "Memory leak" | "The app is holding onto old data it no longer needs, like never closing browser tabs — eventually it runs out of room" |
| Instead of... | Say... |
|---|---|
| "We should use a queue instead of synchronous processing" | "Right now, every request waits in line and gets handled one at a time. We could switch to a system where requests drop off their work and come back for results later — faster for users, but harder for us to track if something fails" |
| "We need to add caching" | "The app asks the database the same questions over and over. We could save recent answers in a notepad so it doesn't have to ask again — much faster, but the notepad might have stale info" |
Pick one analogy family per explanation and stick with it. Don't mix metaphors.
| Domain | Good analogy family |
|---|---|
| Web requests / APIs | Restaurant: kitchen (server), waiter (API), menu (docs), order (request), meal (response) |
| Databases | Filing system: cabinets (tables), folders (rows), labels (columns), index (table of contents) |
| Build systems / CI/CD | Assembly line: raw materials (source code), stations (build steps), quality check (tests), shipping (deploy) |
| Auth / Security | Building security: ID badge (token), front desk (auth server), guest list (permissions), expired pass (token expiry) |
| State management | Whiteboard: what's written on it (state), who can erase/write (actions), taking a photo of it (snapshot) |
| Version control | Drafts of a document: save a copy (commit), make a new version to try something (branch), combine two versions (merge), undo to a previous draft (revert) |
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."
Every technical observation must connect to something the user cares about: speed, cost, user experience, reliability, or "will this break later."