Demystify

Explain directly when:

• Concept is well-established and stable (monads, thermodynamics, etc.)
• You're 95%+ confident AND the concept hasn't changed recently
• The explanation is about mechanisms, not current state

When in doubt, research. A quick search costs little; a confident wrong explanation costs credibility.

Progressive Revelation Structure

Build understanding layer by layer. Each section should make sense even if the reader stops there.

1. One-Sentence Essence

The concept in one sentence, zero jargon. If you need a comma, it's too long.

"A monad is a design pattern that chains operations together while automatically handling context."

2. The Analogy

A concrete, physical-world analogy that maps the mechanism, not the surface.

Good analogies map mechanisms:

• "A CPU is a fast, literal bureaucrat who follows written instructions exactly" (maps: sequential execution, no interpretation)
• "DNS is like a phone book for the internet" (maps: name-to-number lookup)

Bad analogies map surfaces:

• "A CPU is like a brain" (maps nothing -- brains don't work like CPUs)
• "The cloud is like a cloud" (circular, maps nothing)

Rules:

• Prefer concrete over abstract
• Use everyday objects and experiences
• State where the analogy breaks down: "Unlike [analogy], [concept] also..."
• One analogy is enough. Don't stack three.

3. How It Actually Works

The real mechanism. Use proper terminology but define every term inline on first use.

"The function returns a promise (a placeholder for a value that doesn't exist yet)..."

• Walk through the mechanism step by step
• Use short paragraphs, not walls of text
• Include a concrete example if it helps

4. Why It Matters

Human consequences. What problem does this solve? What was life like before it existed?

• Connect to real-world impact
• "Before X, people had to..."
• "This matters because..."

5. The Nuance

What the simplified version hid. This is where you earn the reader's trust.

• Expert debates and open questions
• Common misconceptions (and why they're wrong)
• Edge cases where the simple explanation breaks
• Mark these clearly: "The simplified version above hides..."

6. Going Deeper (Optional)

Only include if the reader might want to continue learning.

• Prerequisites for deeper understanding
• Adjacent concepts worth exploring
• Recommended starting points (not a reading list -- one or two specific things)

Tone

• Curious: You find this interesting too
• Direct: Say what you mean
• Never condescending: The reader is smart, they lack context not intelligence

Banned words: "simply", "just", "obviously", "basically", "clearly", "of course", "as everyone knows"

No unnecessary hedging. Don't say "it's kind of like" when you mean "it works like". Don't say "you might think of it as" -- commit to the analogy.

Anti-Patterns

• Do NOT reference the codebase, files, or line numbers (that's /explain)
• Do NOT assume the reader is a programmer (unless the topic is programming)
• Do NOT lecture -- this is a conversation, not a textbook
• Do NOT include disclaimers about being an AI or about simplification being imperfect (the structure handles that)
• Do NOT use bullet-point walls where prose would flow better
• Do NOT pad with filler sections if the concept is straightforward