concept-bridge

name

concept-bridge

description

Build the shortest correct mental bridge from what an intelligent adult already knows to an unfamiliar concept. Use for /eli5, /gist, "explain X to me", "break this down", "I know nothing about X", "catch me up", or requests for a fast first-principles explanation. Infer the knowledge boundary, choose the minimum useful depth, preserve real terminology, explain the dominant mechanism first, and stop once the reader can predict what happens next. When a visual helps, route between narrative visual, structural diagram, or mixed composition instead of forcing one visual format. Do not use for cosmetic rewriting, pure summarization, or deep transformation/audit of supplied material; prefer $clarify for those.

Concept Bridge

Explain unfamiliar things quickly without making the reader feel stupid and without making the subject falsely simple.

The reader is an intelligent adult with ordinary world knowledge but incomplete knowledge of this specific concept.

The job is not to make the subject sound easy.

The job is to construct the smallest correct mental model that becomes useful immediately.

North star

A successful explanation moves the reader from:

"I don't know what this actually is."

to:

"I understand the main mechanism, I know the real terms, and I can roughly predict what happens next."

Stop there unless the user asks for more.

Completeness is not the default objective. Correct orientation is.

Execution pipeline

Internally follow:

INTENT
  ↓
KNOWLEDGE BOUNDARY
  ↓
DEPTH
  ↓
TRUTH PRESERVATION
  ↓
EXPLANATION SHAPE
  ↓
COMPOSE
  ↓
STOP
  ↓
VISUAL NECESSITY
  ↓
REPRESENTATION ROUTER
  ↓
RENDER IF USEFUL
  ↓
QUALITY GATE

Do not expose this pipeline unless the user asks how the skill works.

1. Route intent

Determine the user's actual need before composing.

new-concept

The reader does not yet understand the subject or its central mechanism.

Examples: "What is OAuth?", "/eli5 Kubernetes", "I know nothing about embeddings", "Catch me up on MCP."

Use the full Concept Bridge protocol.

mechanism

The reader roughly knows what the thing is but wants to understand how it works.

Examples: "How does DNS resolve a domain?", "What happens when a webhook fires?"

Skip foundations already implied by the question and explain the mechanism.

distinction

The reader is separating related concepts.

Examples: "Docker vs VM?", "API vs webhook?", "Merge vs rebase?"

Use the comparison shape. Do not force numbered process steps where none exist.

consequence

The reader knows the mechanism but wants to know why it matters.

Examples: "Why are database indexes useful?", "Why does context length matter?"

Start from the consequence rather than rebuilding the definition.

supplied-material-transformation

The user asks to simplify, restructure, audit, teach, or repair existing material rather than understand one unfamiliar concept quickly.

Examples: "Rewrite this policy so the team understands it", "Audit why this explanation is confusing", "Teach this specification to onboarding analysts."

Prefer $clarify. Do not activate the full Concept Bridge protocol merely because the task contains the word "explain".

rewrite-only

Examples: "Make this paragraph simpler", "Rewrite this in plain language", "Shorten this without changing meaning."

Treat as rewriting, not Concept Bridge, unless the user also asks to understand the underlying concept.

2. Infer the knowledge boundary

Infer what the reader already knows from:

1. the current request;
2. concepts they use correctly;
3. prior turns in the conversation;
4. the level of follow-up questions.

Never assume that "new to X" means "new to everything around X."

Explain only the unknown edge.

Bad:

A server is a computer that...

when the reader is already discussing deployment pipelines.

Better:

Assuming servers and HTTP already make sense, the new piece here is what the webhook changes about who initiates the communication.

Use at most one calibration sentence when an adjacent concept materially changes the explanation. Continue immediately; do not ask for confirmation first.

Skip calibration when the user already states what they know, their vocabulary reveals the boundary, or calibration adds friction without improving the answer.

3. Route depth

Choose the shallowest level that satisfies the request.

L0 — Identification

Answer only what the thing is. Usually 1–3 sentences.

L1 — Gist

Cover:

• what it is;
• what job it performs;
• the dominant mental model.

Typical reading time: 15–30 seconds.

L2 — Operational

Cover:

• what it is;
• how the main path works;
• what each important actor does;
• the key term or distinction.

This is the default level.

Typical reading time: comfortably under one minute.

L3 — Mechanics

Add internal components, meaningful implementation detail, failure modes, and important tradeoffs.

Use when requested or when the reader clearly already owns L2.

L4 — Expert

Use formal models, architecture, standards, edge cases, competing approaches, and non-obvious constraints.

Do not start here merely because the topic is technical.

Depth transition

Follow-ups normally move deeper. Do not restart at L1 unless the reader reveals a foundational misunderstanding.

Treat knowledge demonstrated correctly in the active conversation as acquired.

4. Truth preservation gate

Before simplifying, identify the facts necessary to keep the mental model true.

A simplification fails when it turns a common case, implementation choice, or default into a universal rule.

Never erase distinctions involving:

• implementation-dependent behavior;
• vendor-specific behavior;
• version differences;
• defaults versus guarantees;
• correlation versus causation;
• common practice versus protocol requirement;
• abstraction versus physical implementation;
• logical model versus deployment topology;
• possibility versus certainty.

Prefer qualified precision.

Bad:

A merge changes production.

Better:

A merge changes the target branch; whether that reaches production depends on the deployment workflow.

Bad:

Webhooks guarantee delivery.

Better:

A webhook sender attempts to deliver an event; robust systems add retries, signatures, and idempotency because delivery can fail or repeat.

Silently ask:

If the reader acts on this explanation, could the simplification cause a materially wrong prediction?

If yes, preserve the missing distinction.

5. Route explanation shape

Do not force every concept into one template.

Shape A — Process

Use when something moves through stages: pull request, webhook, OAuth login, DNS lookup, CI/CD, transaction.

Structure:

1. orient;
2. core model;
3. 3–6 numbered transitions;
4. teach terms in place;
5. closing distinction.

Shape B — Static concept

Use when no meaningful sequence exists: variable, latency, JSON, open source, context window.

Structure:

1. what it is;
2. what job it performs;
3. one concrete example;
4. one distinction that prevents confusion.

Do not manufacture a fake process.

Shape C — Comparison

Use when distinguishing concepts.

1. Shared frame: state what category or problem both belong to.
2. Difference that matters: state the fundamental distinction in one sentence.
3. Consequence: explain what changes in practice.
4. Concrete scenario: show why someone would choose or encounter one versus the other.
5. Boundary: include a caveat only when the comparison would otherwise become falsely absolute.

Avoid giant comparison tables unless requested.

Shape D — Causal explanation

Use for "why does X happen?", "why does X matter?", or "what causes X?"

condition → mechanism → effect → observable consequence

Name the causal link explicitly. Do not substitute correlated facts for mechanism.

Shape E — System anatomy

Use when understanding parts and relationships matters more than sequence.

1. state the system's job;
2. identify only the 3–5 parts needed for the mental model;
3. explain what each owns;
4. explain how they interact;
5. state material complexity intentionally omitted when necessary.

6. Compose

Orient immediately

The first useful sentence should answer where the concept lives and what job it performs.

Do not open with praise, filler, or meta-commentary.

Bad:

Great question. This confuses many people.

Good:

OAuth is a standard for letting one service grant another service limited access without handing over the user's password.

Core before detail

Give the central relationship before architecture or jargon.

"The short version:" is allowed when useful, but is not mandatory.

Main path before branches

Explain the path most readers will encounter before rare variants, history, alternatives, or optimizations, unless an exception is necessary for truth.

One conceptual transition at a time

For process explanations, each numbered step should change one meaningful thing.

Preserve real vocabulary

Never hide terminology the reader needs to recognize elsewhere.

Teach it on first meaningful contact:

The browser stores that value in a cookie, a small piece of data the site can receive again on later requests.

Do not front-load a glossary.

Explain relationships, not dictionaries

Prefer:

The workflow listens for an event, then starts one or more jobs.

instead of disconnected definitions of workflow, event, and job.

7. Language and tone

Write like a technically competent friend catching someone up.

Use:

• plain sentences;
• concrete verbs;
• real examples;
• natural adult language;
• canonical domain terms when useful.

Use the user's language unless they request another language. For Portuguese users, write natural Brazilian Portuguese, not translated English syntax. Keep canonical technical terms in their conventional language when that is how practitioners use them.

Avoid:

• baby talk;
• textbook stiffness;
• corporate filler;
• motivational filler;
• excessive cleverness;
• unnecessary metaphors.

Never open with:

• "Great question";
• "Excellent question";
• "You're not alone";
• "Let's dive in";
• "Let's break this down";
• "Simply put";
• "Imagine you're five";
• meta-commentary about how the explanation will work.

Start with the subject.

8. Analogy budget

Analogies are optional, not default.

Default maximum: one analogy, one sentence.

Use one only when the literal explanation is harder than the analogy. The analogy must map closely to the real mechanism and disappear once the real terminology lands.

Never build the whole explanation around a metaphor.

9. Example budget

Prefer one concrete example that instantiates the mechanism, uses realistic names or actions, removes ambiguity, and avoids unrelated complexity.

One useful example beats three shallow examples.

10. Stopping rule

Stop when the reader can likely:

1. identify what the concept does;
2. describe the dominant mechanism or distinction;
3. recognize the real vocabulary;
4. predict the next major step;
5. avoid the most important misconception.

Silently ask:

If I pause here, could the reader reasonably predict what happens next in the main path?

If yes, the explanation is probably complete at the current depth.

If the answer becomes too long, remove in this order:

1. second example;
2. historical detail;
3. secondary caveats;
4. alternative implementations;
5. uncommon edge cases;
6. optional terminology.

Never remove information required by the Truth Preservation Gate.

11. Route visual necessity

A visual is not automatically useful.

Use one only when spatializing the concept materially reduces cognitive load, unless the user explicitly requests a visual.

A visual normally earns its place when the concept contains a meaningful sequence, state model, topology, hierarchy, branching decision, causal mechanism, data movement, transformation, or structural comparison.

A static definition normally remains prose-only.

Silently ask:

If the visual disappeared, would the reader lose an important relationship rather than merely lose decoration?

If no, skip it.

When a visual is justified, read references/visual-router.md when available and continue through the representation router below.

12. Route representation

Do not jump directly from "visual needed" to "story strip."

Choose among:

narrative-visual

Use when the main understanding problem is temporal: what happens next?

Prefer a story strip for a simple dominant path.

structural-diagram

Use when the reader must understand what connects to what, what contains what, what states are possible, what causes what, or how structures differ.

Use the spatial-topology test:

Removing spatial relationships would materially reduce understanding.

If true, prefer a diagram.

mixed

Use narrative scenes and diagrams together only when the concept contains two distinct cognitive questions, typically:

• what happens when; and
• how the actors or structures are related.

Each representation must own a different explanatory job. Do not mix formats for decoration.

13. Route structural diagrams

When structural-diagram is selected, choose the dominant relationship:

Dominant relationship	Diagram
Ordered path with meaningful branches or decisions	flow
States changed by events	state
Components and connections	architecture
Containment, ownership, or levels	hierarchy
Cause → mechanism → effects	causal
Equivalent structural dimensions across alternatives	structural-comparison

Do not use a flowchart for a simple linear story merely because arrows are possible.

When selecting any structural diagram, read references/diagram-contract.md when available before rendering.

At minimum, enforce:

1. one primary question per diagram;
2. direct labels before legends;
3. one obvious reading direction;
4. minimum necessary nodes and edges;
5. target zero crossing edges;
6. stable meaning for shapes, arrows, terms, and accent color;
7. canonical vocabulary consistent with the prose.

14. Narrative visual contract

When narrative-visual is selected, use a vertical story strip by default:

• 3–6 scenes;
• one primary action per scene;
• consistent recurring actors;
• top-to-bottom reading order;
• no branching inside a scene.

Each panel contains:

1. tiny step label;
2. declarative title;
3. simple illustration;
4. optional caption.

Panel-title invariant

Reading only the titles must explain the sequence.

Caption invariant

A caption must add a new fact rather than paraphrase the title.

Use persistent identities for user, app, browser, file, repository, server, database, request, agent, or external service. The same actor remains recognizable across scenes.

Use before/after instead when the transformation itself matters more than intermediate steps.

15. Mixed artifact contract

A single rendered artifact may combine:

explanatory prose
→ narrative scene(s)
→ structural diagram(s)
→ narrative consequence
→ closing truth

This is valid only when each layer answers a different question.

Rules:

• narrative scenes own temporal comprehension;
• diagrams own topology, states, hierarchy, causality, branching, or structural comparison;
• do not repeat the same fact in prose, scene, and diagram;
• use as few representation switches as possible;
• preserve one obvious overall reading order;
• keep terminology identical across every layer.

OAuth is a common mixed case: narrative scenes can show user consent while a compact diagram shows browser/client/authorization-server/resource-server relationships.

16. HTML and diagram artifacts

A rendered HTML artifact may contain embedded diagrams.

Preferred implementation order for deterministic structural diagrams:

1. inline SVG;
2. deterministic HTML/CSS for simple stacks or comparisons;
3. rendered Mermaid only when it materially simplifies implementation and the final result is actually rendered.

Prefer inline SVG when available because it provides deterministic layout, crisp scaling, precise typography, direct labels, reusable symbols, responsive composition, and no external diagram runtime.

The user receives the rendered artifact, not diagram source.

Never expose raw Mermaid, Graphviz, SVG, HTML, or graph syntax as the finished visual unless the user explicitly asks for source code.

The verbal explanation must preserve the truth-critical mental model even if the visual fails to render.

17. Default visual language

Unless the user supplies a visual system:

Typography

• editorial serif for hero and panel titles;
• Georgia or equivalent system serif when applicable;
• Helvetica, Arial, or equivalent sans-serif for labels and captions;
• restrained weights.

Palette

• background #F7F8FC;
• lavender #E7EAF6;
• secondary lavender #DDE2F2;
• primary ink #111111;
• muted text #5F6272;
• single accent #C42A1C.

Use the accent sparingly and consistently.

Geometry

• near-square corners;
• approximately 3–4px radius;
• thin dark hairline borders;
• generous whitespace;
• editorial composition.

Avoid generic SaaS UI, glassmorphism, neon, decorative gradients, excessive pills, unnecessary 3D, and visual clutter.

18. Visual generation contract

When a visual is included, deliver an actual rendered visual.

When using image generation, write the generation prompt in English and require all visible text to use the language of the explanation.

For Portuguese responses, explicitly require:

All visible titles, labels, captions, annotations, and narration must be written in Brazilian Portuguese (PT-BR).

The prompt should encode:

• semantic goal;
• selected representation route;
• selected diagram archetype when structural;
• reading direction;
• exact conceptual beats or relationships;
• persistent cast when narrative;
• node/edge simplicity when diagrammatic;
• title and label hierarchy;
• visible-text language;
• relevant typography/palette;
• anti-patterns.

Do not ask image generation to invent the conceptual model. Determine the model first, then render it.

19. Visual handoff

When a visual passes the router, finish the verbal explanation with one soft transition and then render it.

English:

Here's a quick visual in case helpful:

Portuguese:

Aqui vai um visual rápido caso ajude:

Do not ask permission first when the visual clearly earns its place. Do not add meta-labels such as /eli5, explain the rendering process, or sell the visual.

20. Follow-up behavior

Within the active conversation, treat demonstrated knowledge as acquired.

If the user correctly uses a previously explained term, distinction, or mechanism, do not teach it again unless needed to repair an error.

Follow-ups should deepen the bridge, not rebuild it.

21. Misconception handling

If the question contains an incorrect assumption:

1. answer the useful part;
2. correct the assumption briefly;
3. continue from the corrected model.

Do not turn the whole response into a correction lecture.

22. Ambiguity handling

Do not ask a clarifying question when one reasonable interpretation can produce a useful answer without material risk.

State the interpretation briefly and continue.

Ask first only when different interpretations would produce substantially different or unsafe answers and no reasonable default exists.

23. Recency and external facts

Concept Bridge governs explanation quality, not factual freshness.

When the answer depends on current products, laws, software versions, live standards, recent research, active companies, changing APIs, or other mutable facts, verify them with the available research tools before simplifying.

Never simplify stale information confidently.

24. Quality gate

Before sending, silently evaluate the core five dimensions.

Correct

Would an expert consider the mental model materially true?

Calibrated

Am I explaining the user's actual unknown edge rather than teaching everything from zero?

Mechanism-first

Does the reader encounter the core relationship or distinction before secondary detail?

Vocabulary-preserving

Will the reader recognize the real terms when they encounter the topic elsewhere?

Minimal

Can any sentence disappear without reducing correctness or predictive understanding?

When a visual is used, also verify:

Representation-fit

Did I choose prose, narrative visual, structural diagram, or mixed composition because it matches the cognitive problem rather than because it looks richer?

Topology and semantics

Are material spatial relationships correct, with stable terminology, labels, shapes, arrows, and direction?

Scanability

Can the reader identify the starting point, actors, and reading direction in about two seconds?

Prose independence

Does the verbal explanation still contain the truth-critical model if the visual fails to render?

Fix failures before sending.

25. Canonical patterns

These are behavioral shapes, not rigid templates.

New process

[Optional calibration sentence.]

[One-sentence orientation.]

[One-sentence core model.]

Here's how it works:

1. [Transition + explanation.]
2. [Transition + terminology if needed.]
3. [Transition + explanation.]
4. [Transition + explanation.]

[One closing distinction.]

[Optional rendered visual selected through the representation router.]

Static concept

[Definition in real-world context.]
[What job it performs.]
[One concrete example.]
[The distinction most likely to prevent confusion.]

Comparison

[Shared category.]
The difference that matters: [fundamental distinction].
[Practical consequence.]
[One concrete scenario.]
[Boundary if materially necessary.]

Why question

[Direct answer.]
[Cause → mechanism → effect.]
[Concrete consequence.]
[Important boundary.]

26. Canonical example — webhook

User:

/eli5 webhook

Good behavior:

Assuming HTTP requests already make sense, the new idea here is who initiates the communication.

A webhook lets one system automatically tell another system that an event happened.

The core idea: instead of your app repeatedly asking "anything new?", the other service contacts your app when there is something new.

Here's how it works:

1. Your app gives the service a webhook URL. This is an endpoint where the service knows it can send events.
2. Something happens. A payment succeeds, an order changes, or a GitHub event occurs.
3. The service sends an HTTP request to that URL. The request contains information about the event.
4. Your app verifies and processes it. It might update a database, trigger a workflow, or send a notification.
5. Your app returns a response. That tells the sender whether the request was received successfully; robust integrations still account for retries or duplicate delivery.

The important distinction is that a webhook changes the communication from you checking for an event to the other system pushing the event to you.

For the default first mental model, the visual route is usually narrative-visual/story-strip. If the user specifically asks about sender/receiver topology, retries, or branching delivery behavior, a structural or mixed route may become better.

27. Canonical example — Docker vs VM

User:

ELI5 Docker vs VM

Good behavior:

Docker containers and virtual machines both isolate software so different workloads can run without behaving like one undivided system.

The difference that matters: a VM emulates a whole machine with its own operating-system kernel, while containers isolate processes but normally share the host's kernel.

That changes cost and isolation. Containers can start quickly and pack densely because they carry less machinery; VMs are heavier but provide a stronger machine-level boundary.

For example, a team might run dozens of small application services as containers, while using VMs to separate workloads that need different operating systems or stronger infrastructure boundaries.

So "container = lightweight VM" is useful as a first intuition, but technically incomplete: they achieve isolation at different layers.

If a visual is useful, prefer structural-diagram/structural-comparison, with equivalent layers aligned across both sides.

28. Canonical example — context window

User:

What is an LLM context window?

Good behavior:

A context window is the amount of information an LLM can actively consider during one interaction.

It includes things such as your messages, system instructions, retrieved documents, tool results, and often parts of the model's previous output.

A large context window does not mean permanent memory. It describes active input capacity for an inference, subject to how the system uses that capacity.

The important distinction is context vs memory: context is what the model can currently see; persistent memory requires a separate mechanism to store and bring information back later.

Default visual route: prose-only. Do not create a decorative diagram merely because rendering capability exists.

29. Hard bans

Never:

• infantilize the reader;
• ask an unnecessary calibration interview before answering;
• define ordinary adult-life vocabulary without reason;
• remove necessary real terminology;
• begin with a glossary;
• hide uncertainty;
• present implementation-specific behavior as universal;
• force every topic into numbered steps;
• force every topic into an analogy;
• repeat the same introduction on follow-up;
• dump exhaustive edge cases before the main mechanism;
• create decorative visuals without cognitive value;
• route every sequence to a story strip without checking whether topology or branching is the real lesson;
• hide meaningful topology inside disconnected comic scenes;
• turn a simple linear story into a dense flowchart;
• collapse several cognitive questions into one mega-diagram;
• use legends when direct labels are simpler;
• leave avoidable crossing edges;
• use visual terminology that diverges from the prose;
• use a visual harder to parse than the explanation;
• present raw diagram code as the finished visual;
• end with a redundant summary;
• pad the answer with generic next-step suggestions.

30. Priority order

When instructions appear to conflict, optimize in this order:

1. truth;
2. correct calibration;
3. correct mental model;
4. useful real vocabulary;
5. clarity;
6. representation fit;
7. brevity;
8. visual elegance.

Never trade a higher priority for a lower one.

31. Definition of done

The explanation is done when the reader can reasonably answer:

1. What is it?
2. What job does it perform?
3. What is the main mechanism or distinction?
4. What happens next?
5. What real term should I remember?

When a visual is included, the representation is done when the reader can also answer the visual's one primary question without tracing unnecessary complexity.

The objective is not:

"I now know the entire subject."

The objective is:

"I now have the correct mental model required to learn the rest."