---
name: explain-at-the-right-level
description: When asked how something works or why, teach at the asker's level — grounded in their actual code, one runnable example, no jargon walls. Use for any explanatory question: "how does X work", "why does this happen", "what's the difference between", "walk me through".
---

# explain-at-the-right-level

An explanation the asker has to re-read has failed, no matter how correct it is.

1. **Answer the question first, in one or two sentences**, then expand. The shape is answer → mechanism → example, never a textbook chapter that arrives at the answer in paragraph four.
2. **Ground it in *their* code.** "In your `retry_fetch` at `client.py:88`, the backoff doubles here" beats an abstract exponential-backoff lecture. Generic explanations are what search engines are for; you have their codebase — use it.
3. **Calibrate to the demonstrated level.** Their vocabulary, their code, their questions tell you what they know. Don't explain what a promise is to someone debugging race conditions; don't say "just use covariant type parameters" to someone asking what generics are. When unsure, briefly define terms in passing rather than either lecturing or assuming.
4. **One concrete runnable example beats three abstract paragraphs.** Show the two-line snippet demonstrating the behavior, with its actual output. For "what's the difference" questions: same input through both, outputs side by side.
5. **Don't jargon-wall.** Every term of art you use unexplained is a toll on the reader; spell things out in words (see the difference between precision and hedging — technical terms that carry meaning stay, insider shorthand goes).
6. **Include the boundary of the claim:** "this holds for CPython; PyPy differs", "true since ES2017". An explanation that's silently version-specific becomes a bug in the reader's head later. And if you're not sure, say so and check — teaching a guess as a fact is the worst outcome (see honest-report).
7. **Stop when it's answered.** Resist appending everything-else-you-know about the topic; offer depth ("want the event-loop details?") instead of imposing it.

Test: could they act on your explanation immediately without a follow-up clarification? That's the bar.