Eli5

@rules/explanation-method.md @rules/validation.md @references/upstream-eli5.md

ELI5

Make a difficult idea usable for a particular reader without making it false, patronizing, or merely shorter.

Default user-facing explanations, examples, handoff notes, and validation notes to Korean. Preserve code identifiers, commands, file paths, API names, schema keys, mathematical notation, and quoted source text in their original form.

Use another language when the user requests it or the target reader requires it. Match the target reader's vocabulary, not the language of this canonical file.

• Build an explicit reader model from knowledge, goal, context, and constraints instead of relying on age stereotypes.
• Preserve the topic's causal spine: what it is, how it works, why it matters, and where the explanation stops being exact.
• Explain in layers so the reader gets a useful answer first and can descend into mechanism only as needed.
• Make analogies earn their place, label where they break, and never substitute a metaphor for the actual mechanism.
• Turn explanation quality into a bounded pre-send check with regression cases.

Use eli5 when the primary deliverable is an explanation calibrated to a named person, role, age, education level, prior knowledge, or requested simplicity/depth level.

Route elsewhere when:

• the user wants a short summary but gives no teaching or audience-calibration intent — summarize directly
• the user wants code changed, a bug fixed, or a feature implemented — use the implementation skill; apply eli5 only to the explanation portion if requested
• the user wants ADHD-shaped output rather than conceptual simplification — use adhd-explainer; both may compose when both intents are explicit
• the user wants a reusable prompt, document, or skill artifact — use prompt-maker, docs-maker, or skill-maker
• the user asks for personalized medical, legal, or financial judgment — preserve uncertainty and professional boundaries; simplification may clarify general information but must not manufacture a recommendation

This skill owns explanation design, not the truth of unread source material. Read the relevant code, error, document, diagram, or source before explaining it.

Positive:

• "ELI5 how database indexes work."
• "이 에러가 왜 나는지 신입 개발자도 이해하게 설명해줘."
• "Explain this architecture decision to my manager."
• "양자 얽힘을 고등학생 수준으로, 비유의 한계도 알려줘."
• "I know Python but not Rust; explain ownership from that starting point."

Negative:

• "Summarize this meeting in three bullets." (compression, not teaching)
• "Fix the database migration." (implementation)
• "Write a reusable system prompt that explains code to interns." (prompt artifact)
• "Based on these symptoms, tell me which medication to take." (personal medical judgment)

Boundary:

• "Fix this race condition, then ELI5 the cause for support." Use the implementation skill for the fix and this skill for the explanation.
• "ELI5 OAuth, but keep the exact threat model and protocol terms." Simplify the path through the concepts, not the security facts.
• "Explain this to a five-year-old and include the full proof." State the conflict and provide a child-level intuition plus a separate formal layer.

Infer only what the request supports. Use this order:

1. Goal — decide, debug, learn, teach someone else, or satisfy curiosity.
2. Starting knowledge — named concepts they know, role, course level, or evidence from the conversation.
3. Context — work, school, home, codebase, incident, or decision.
4. Constraints — length, format, language, required terminology, accessibility, or precision.

Age and role are weak proxies. Never infer intelligence, interests, family structure, technical ability, or preferred analogy from age, gender, relationship, or job title alone. If no audience is given, use an intelligent beginner: plain language, correct terms defined on first use, and no childish tone.

Use only the layers the request needs, in this order:

1. Gist — one or two sentences answering "what is it?"
2. Concrete model — an example, visual model, or analogy connected to known experience.
3. Mechanism — the real actors and cause-and-effect sequence, with essential terms defined once.
4. Why it matters — the decision, failure, behavior, or consequence relevant to this reader.
5. Boundary — where the model stops matching reality, or the key trade-off/uncertainty.
6. Check — one low-pressure teach-back question only when the user asked to learn, study, or confirm understanding.

For a one-line question, a one-line answer may be complete. For a technical or safety-critical topic, layers 3 and 5 are usually required.

• Lead with the answer, not praise or a plan announcement.
• Preserve the causal spine and every safety- or decision-relevant caveat.
• Define necessary terms at first use, then use the correct term consistently.
• Prefer one strong example over several decorative analogies.
• State an analogy's mismatch when believing it literally would mislead the reader.
• Separate "what the source says" from "a way to picture it."
• Match depth to the user's goal; professionals may need fewer basics and more trade-offs.
• Explain code by purpose, inputs/outputs, control/data flow, then syntax details when useful.
• Explain errors by visible symptom, root cause, smallest correction, and prevention or verification.

• Do not default unspecified ELI5 requests to baby talk or a literal five-year-old persona.
• Do not trade material accuracy for a memorable story, even when the source skill permits "80% accuracy."
• Do not assume toys for children, social media for teenagers, home ownership for adults, or household roles by gender/relationship.
• Do not use "obviously", "simply", "just", "easy", "dumbed down", or language that shames missing knowledge.
• Do not stack analogies before naming the real concept.
• Do not remove protocol, medical, legal, financial, or security caveats to sound simple.
• Do not quiz the reader unless learning or comprehension checking is part of the request.
• Do not over-format a tiny answer or repeat the gist as a closing summary.
• Do not explain unread code, logs, files, or current product behavior as verified fact.

1. Read rules/explanation-method.md for audience calibration, analogy rules, and domain-specific explanation patterns before drafting a non-trivial explanation.
2. Read rules/validation.md before the final response and whenever this package changes.
3. Read references/upstream-eli5.md only when reconciling this package with its upstream inspiration, attribution, or evaluation claims.
4. Use assets/evals/eli5-cases.jsonl when changing trigger, workflow, safety, or output behavior.

• The response answers the actual question in its first layer.
• The reader model uses stated evidence and no demographic stereotype.
• The causal mechanism and critical caveats remain true after simplification.
• Every required technical term is defined once and then used consistently.
• Any analogy helps, maps to the mechanism, and names its important limit.
• Length, tone, format, and depth fit the target reader's goal.
• Unread or uncertain source behavior is marked unknown rather than invented.
• Package changes preserve English/Korean structure and all eval categories.
• Package changes run node skills/skill-tester/scripts/validate-skills-corpus.mjs --root skills --only eli5 --json.
• Package changes run bun run --cwd scripts verify.