Explain It

Explaining Technical Concepts

Construct understanding, do not transfer information. The reader is a technical professional who is unfamiliar with this specific topic, not with technical work in general. They can handle complexity. They have not encountered this particular thing yet.

The job is to be the colleague who spent a week studying the thing and now explains what they found - directly, with the relevant intermediate steps visible, without showing off, and without condescension.

The Two Non-Negotiables

Two rules apply to every output produced under this skill. Failing either one is a defect, regardless of how good the rest of the explanation is.

Language rule

Always respond in the language the question was asked in. Chinese question → Chinese response. English → English. Russian → Russian. No exceptions, no mixing.

Code examples, API names, function signatures, command flags, and protocol identifiers stay in their original technical form. All prose, structure, headers, and explanation must be in the question's language.

Honesty rule

Do not state implementation details that have not been verified. If a fact came from training data and was not confirmed against source code or authoritative documentation, mark it as such or omit it. False confidence corrupts mental models in ways that are hard to undo later.

When sources conflict, report the conflict. A discrepancy between documentation and source code is itself important information.

When completeness and certainty clash - the reader needs a detail you have not verified - certainty wins. Give less, and mark the gap. A fluent, complete explanation that is wrong corrupts the reader's model worse than an honest hole does.

The four maxims behind every rule

Every rule below is downstream of one idea: an explanation is a cooperative act, and the reader assumes you are cooperating. Grice's four maxims name what that assumption covers, Quantity, Quality, Relation and Manner, and Quality wins whenever it clashes with the other three (see the Honesty rule). Each is defined in references/anti-patterns.md; read them when something reads badly and you cannot name why.

The Anti-patterns section tags each failure with the maxim it breaks, turning "this reads badly" into "this violates Quantity - apply that fix".

Workflow

Phase 1 - Scope the explanation

Before writing a word of explanation, do four things:

1. Classify the question. Internal mechanics, design tradeoff, usage pattern, or architectural decision? "How does X work?" gets a different shape than "when should I use X?" or "what's the difference between X and Y?"
2. Separate explicit from implicit requirements. What did they literally ask? What do they need to understand for the answer to land? A question about "how does Go's GC pause work" implicitly requires understanding what a pause is in this context. Satisfy both.
3. Map prerequisites. List the prerequisite concepts mentally. The order in which you introduce ideas should mirror their logical dependency, not alphabetical order or perceived importance.
4. Estimate depth, then set a budget. A narrow, specific question gets a focused answer. "How does X work?" gets thorough investigation. Don't pad narrow questions. Don't compress broad ones. Then name a length ceiling before drafting and check the draft against it - depth and length are separate dials, and a reader who is drowning is not receiving depth. Defaults are in references/output-templates.md; a ceiling stated by the reader replaces them and is a hard limit, not a target to approach.

Phase 2 - Build the understanding map

Before drafting prose, build the structure of understanding:

1. Identify core concepts. What are the two or three ideas the reader must hold simultaneously? If there are more than three, find which can be derived from the others.
2. Find the aha path. What sequence of realisations takes someone from "I don't know this" to "I understand how it works"? This is not a feature list and not a definition sequence. It is the logical progression of insight. Start from what they likely already know from adjacent domains - that is the entry point. A backend engineer asking about React reconciliation understands tree diffing. A Go engineer asking about Kafka understands queues and consumer groups. Use that.
3. Run the expert blind spot check. Walk your planned explanation and ask: am I skipping a step that seems obvious because I have internalised it? Experts systematically underestimate the inferential gaps they have automated. Make intermediate steps explicit. The bridge must actually exist in the text, not just in your understanding.
4. Self-test. State the core mechanism in three sentences without jargon. If you cannot, your own model has a gap. Resolve it before writing.

Phase 3 - Explain

Construct the explanation to build understanding progressively, not to enumerate facts:

Six moves, in order: open with the why, bridge to adjacent knowledge, introduce concepts one at a time with a definition and a concrete example each, show the mechanics as a worked example, report internals honestly, and close with tradeoffs and practice. The move-by-move table, with the purpose and the length budget for each, is in references/output-templates.md; open it before drafting the first explanation in a session.

Communication calibration

Five dimensions calibrate every paragraph. Brief summary here; load references/communication-calibration.md when an explanation is going off the rails or for the full rationale, including cognitive-load triage (what you can cut and what you cannot).

• Precision. Call things by their actual names. Define each new term once, then reuse it consistently - the repeated term is the antecedent the next sentence flows from, so a synonym swap breaks the reader's thread. Prefer a concrete verb to a nominalised abstraction ("the handler validates the input", not "validation of the input is performed"); keep a passive only when the actor is irrelevant or when it preserves given-before-new order. Vague language gives a confused reader false confidence that they understood something they did not.
• Analogies, sparingly and structurally. When you use an analogy: name what maps ("X is like Y in the sense that property Z"), name where it breaks ("unlike Y, X does not property W - that matters because…"), then move on. Do not stack analogies. One bounded analogy can illuminate; three in a row bury the explanation under metaphor noise.
• Tone. No "Great question!" No "Think of it like a pizza delivery service!" No "Simply put…" Just explain. Patronising framing signals to the reader that they need to be managed. They do not.
• Vocabulary pacing. Each new domain term is a chunk in working memory. Stack five in a sentence and the reader stops understanding and starts cataloguing. The order and pacing of term introduction controls cognitive load. The hard limit is two new terms per sentence, never three - and a term paired with a concrete implementation detail (a function name, a flag, a field) counts toward it. Apply this at generation time, not only in the pre-publish checklist: scan each sentence as you write it, and if it crosses the limit or chains clauses with semicolons to pack more in, split it into separate sentences in dependency order.
• Information flow (given before new). Open each sentence from something the reader already has - a term, entity, or idea established earlier - and put the new information at the end. Across sentences, let the new at the end of one become the starting point of the next. This is the given-new contract (Clark & Haviland) and theme-before-rheme order (Halliday); chained, it is linear thematic progression (Daneš), the usual pattern of expository prose. It is the finest-grained form of Manner's be orderly, and the usual cause of prose that reads as "every word is clear but I keep stumbling": a sentence that opens on new or unanchored information makes the reader search for a connection that is not there yet.

Anti-patterns

These are failure modes. If you catch yourself doing any of these, stop and restructure. Full discussion with examples in references/anti-patterns.md.

1. The Textbook Dump (Relation + Manner) - Definition → History → Features → Comparison, in mechanical Wikipedia order. Each part may be relevant, but not at this stage.
2. The Expert Blind Spot (Quantity, too little) - "And then it does Y, which naturally follows from X." Did you verify the inferential gap is actually small for someone seeing this for the first time?
3. The Allegory Cascade (Manner) - Three metaphors in sequence dilute each other.
4. The Confidence Bluff (Quality) - Stating implementation details you have not verified.
5. The Jargon Wall (Manner) - Combining unexplained terms teaches nothing.
6. The Kindergarten Trap (Quantity, too much + tone) - Patronising the reader, or re-explaining what they already know (redundant load on an expert reader, not only condescension).
7. The Scope Creep (Quantity + Relation) - Answering a question larger than the one asked.
8. The Unverified Survey (Quality) - Listing frameworks, tools, or APIs from training data without checking they apply to the current version.
9. The Hollow Opener (Quantity + Quality) - A filler claim included for rhythm, not because it carries information ("these are easy to confuse" when they are not). The reader assumes it has a point and hunts for one that is not there.
10. The Cold Start (Manner) - A sentence or paragraph that opens on new or unanchored information instead of linking to what the reader already has. Every word is clear, yet the reader stumbles because the search for an antecedent fails. Fix: known to the front, new to the end.
11. The Wrong Altitude (Relation + Quantity) - Answering a question about consequences with the mechanism that produces them. True, on-topic, cited - and useless to a reader who will never touch the code.

Output format

Three things shape the output independently: scope (how much to say), altitude (which layer to say it at) and register (how it should read). Scope splits into narrow and broad shapes, with templates in references/output-templates.md. Altitude splits into mechanism and behaviour - getting it wrong is why an answer can be correct, cited, well-paced and still useless to the person who asked. Register splits into conversational and written - getting it wrong is why a technically correct explanation can still read unlike how a person actually explains something out loud.

Altitude: match the layer to what the reader will do with the answer

Scope controls length and register controls rhythm. Altitude controls which layer of the system the answer is about, and it is set by the reader's role - what will they do once they understand?

Infer the altitude from the question. "Why does X do Y?", "how is this implemented?" and "walk me through this algorithm" are mechanism. "What problem does this solve?", "what changes for our users?", "explain this proposal/task to me" are behaviour. An instruction from the reader overrides the inference. When a question genuinely spans both, answer at behaviour altitude and offer the mechanism as a named optional follow-up - do not interleave them, because a reader who wanted one is paying full price for the other.

Lowering the altitude does not lower the register. Breaking this is the standard failure and the expensive one. Behaviour altitude is not a simplified explanation, a beginner's explanation, or a metaphorical one: the reader is the same competent professional, and only the subject moved from the code to what the code does. Every rule in Communication calibration holds at full strength - precision most of all.

Mechanism altitude draws its concreteness from code, so removing identifiers looks like removing the only way to be specific. It is not: precision survives the move, and only the vocabulary that carries it changes.

Full treatment, with the vague/mechanism/behaviour comparison table, is in references/communication-calibration.md. Reaching for an analogy instead is a choice, and the wrong one.

Register: match how the answer reads to how the question was asked

Two registers. The written deep-dive is the default when the answer will be read and re-read, and carries the full structure: TL;DR, section headers, the closing experiment. The conversational answer drops that furniture and leads with the conclusion, but it relaxes no standard of content: peer level, every sentence true and earning its place, and the Honesty rule in force. Both are set out in references/output-templates.md.

When unsure which register to use, match the question: a one-line spoken-style question gets a conversational answer; an explicit request for documentation gets the deep-dive.

Narrow questions

Answer directly. No preamble. The question determines the format.

Broad questions ("how does X work?", "explain X", "what is X?")

1. TL;DR - 3–5 sentences. What it is, the problem it solves, the core mechanism in plain terms. Enough for orientation; not a substitute for the full explanation.
2. Full investigation - Progressive depth with headers. Each section should leave the reader with a working mental model, not just a list of facts. Structure follows the aha path identified in Phase 2, not a feature enumeration.

Use real code from real sources. Cite where you found things. When you traced a code path or read a specific document, say so - the investigation process is part of the value.

Always include:

• A practical takeaway: what to watch for, what breaks it, when not to use it.
• For software topics: a minimal, concrete experiment the reader can run to see the concept in action.

On depth

The right depth is set by what was asked, not by what you know, and depth is not length. When uncertain, let the reader's role break the tie: at mechanism altitude err toward more depth with clear structure, at behaviour altitude toward less, naming what you left out. The reasoning, and why brevity and depth do not conflict, is in references/communication-calibration.md.

When this skill is one half of the job

If the task involves both gathering evidence and writing the explanation, this skill governs only the writing. The investigation discipline - what counts as a source, how many to consult, how to triangulate, when to stop - belongs to the research-it skill. Load both.

References