teach-me

Skill: teach-me

WHAT

Purpose and context

• Purpose: explain ONE thing using a fixed seven-step framework, tailored to the listener, with the "How it works" step evidenced by real runtime and then cleaned of instrumentation.
• Trigger (when to use):
  • User wants to deeply understand ONE specific thing: a file, a function, a feature, a subsystem, a concept, an error message — "how does this work", "explain this to me".
  • User wants that thing explained to ONE specific LISTENER — "ELI5", "how do I tell my boss", "explain it to a designer", "make my parents understand".
• Non-goals: NOT for: understanding an entire unfamiliar codebase (that is /onboard-codebase → wiki, or /join-project → fast read-only orient). teach-me is narrow and deep, it does not write a wiki.

Mental model

người nghe → phạm vi + nguồn → quan sát runtime (đầu vào → state ở dòng nào) → Người nghe · TL;DR + so sánh → 7 phần → So what (độ sâu theo người nghe) → dọn instrument.

Input and output contract

	Field	Required?	Meaning
In	the thing to explain	yes	unclear → ask one question with suggestions
In	listener	no	defaults to engineer; "ELI5" with no one specified → 5-year-old
Out	answer following the Output framework	yes	all blocks, in order
Out	diagram	yes	default inline mermaid; HTML explainer only when the user agrees
Out	user's code clean of instrumentation	yes when instrumentation was inserted	git diff confirm

Rules and capabilities

• RULE-01 (MUST): Complete framework, correct order, no merging or skipping — Listener → TL;DR → seven parts → So what. If one part is missing (even when "obvious" or "not applicable"), say clearly why it is missing, do not silently skip it.
• RULE-02 (MUST): Listener changes HOW IT IS SAID, not the TRUTH — details may be omitted, strong simplification is allowed for non-technical people (conveying 80% of the core idea is better than 100% accuracy that makes the listener give up), but do NOT say anything false; where heavily simplified, note "(simplified)". When compressing evidence into one sentence for a non-technical person, that sentence must not speak louder than what was observed (saw one case → say "one case", do not say "always"); numbers (number of edits, lines, files) are recounted from git/disk, not estimated.
• RULE-03 (MUST): Never use a condescending tone — explaining to a 5-year-old must feel exciting, not "dumbed down"; explaining to a manager must feel empowered to decide, not treated as if they don't understand.
• RULE-04 (MUST): Non-technical listeners = no code, including backticks — no code blocks, no formatting inline code for file/folder names (lesson from eval eli5: the version with the skill still failed because it used backticks around folder names when writing for a manager).
• RULE-05 (MUST): Prove by runtime, don't guess: the "How it works" section should prioritize DRIVING real code. Only when it can't be run (missing environment, needs prod) should you explain statically — and state clearly "this is a static explanation, not yet proven by running". Claims that depend on unobserved runtime → record as debt in [[150726-unknown-ledger]], don't assert blindly.
• RULE-06 (MUST): Temporary instrumentation → CLEAN UP: every print/breakpoint/debugger/console.log inserted for observation must be removed; git diff confirm before finishing.
• RULE-07 (MUST): Scope of ONE thing: teach-me does not analyze the whole project (that's /onboard-codebase//join-project) and does not write wiki.
• RULE-08 (MUST): Don't spawn a new debugger — use available tools (pdb/debugpy · node --inspect · print/log · /run · /verify).
• RULE-09 (MUST): Trade-offs and Limitations must not be conflated — Trade-off is a DELIBERATE exchange at design time; Limitation is a boundary it CANNOT CROSS even if it wanted to, usually revealed in real use.
• RULE-10 (MUST): For multi-item series, count by surface, not by number of articles — when teach-me is called repeatedly to build a lesson set for the whole app (or the user asks "is it enough yet"), do NOT report "N articles" as if everything is covered: run skill surface-coverage (surface-coverage.py scan + check) and report N/M mục bề mặt được phủ along with the list of items that don't have articles yet (GH#191).
• Capabilities: read code/docs; run code locally with available debugger/log; write temporary instrumentation (remove before finishing); do not write wiki.

Failure boundaries

• Can't run (missing environment, needs prod) → explain statically, state clearly not yet proven by running; unobserved claims → record debt in unknown-ledger.
• Ambiguous scope → clarify in one sentence.
• Request to understand the whole project → cancelled, switch to /onboard-codebase//join-project.
• Still instrumentation in git diff → not done.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	question	Identify the audience	one group + what they care about	not stated → engineer
W02	judgment	the thing that needs explaining	Identify the scope + read the right type of source	understand the purpose	unclear → ask
W03	effect	code/small case	DRIVE runtime with a specific input + temporary instrument	at least one runtime observation	cannot run → B01
W04	judgment	observation + audience	Generate output according to the Output framework, depth according to the table	all blocks present	—
W05	deterministic	code already inserted	Remove instrument, git diff	clean diff	still there → keep removing

Details of each step (source of truth for W01–W05):

1. Identify the AUDIENCE — read the question, classify it into one group in the "Audience" table below. Not stated → default the person asking = engineer (teach-me is a dev skill); for the keyword "ELI5"/"like for a 5-year-old" without anyone else → 5-year-old. → Done when one group + what they care about is settled.
2. Identify the scope + read the source — the user names the thing that needs explaining; unclear → ask one question with a hint from context. Read the right type of source: code → read the code, understand the purpose before the syntax; concept → break it into core components; error message → find the root cause, do not retranslate the surface wording; documentation → extract the points that are truly important to the audience.
3. DRIVE runtime (if it can run) — run with a specific input, add a temporary instrument/breakpoint, observe the real state. If the instrument is inserted into the user's code, do it on a copy or remove it in step 5. → Done when there is at least one specific runtime observation (input → state at which line). Cannot run → write "static explanation" (Rules section).
4. Generate output according to the "Output framework" — Audience line → TL;DR + analogy → seven sections IN THE CORRECT ORDER → So what; depth of each section according to the "Depth by audience" table. → Done when all blocks are present, no section is left empty or collapsed into another section.
5. CLEAN UP the instrument — remove every print/breakpoint/debugger temporarily inserted; git diff confirm the user's code is clean as before. → Done when the diff no longer contains a temporary instrument.

Branches

ID	Kind	Guard	Behavior	Skip / failure	Rejoin
B01	recovery	cannot run code (missing environment, needs prod)	static explanation, state clearly "this is a static explanation, not yet proven by running"	assertion not yet observed → unknown-ledger debt	W04
B02	user_optional	user wants to keep/share/needs a nice visual	HTML explainer per /docs-site-macos, call diagram /diagram	does not agree → mermaid inline	W05
B03	conditional_required	non-technical listener	no code block, no backtick; evidence compressed into one sentence	—	W05

Validation and stopping

Checkable: enough blocks and in the right order, no code/backtick for non-technical listeners, git diff clean instrument. Needs eyes: the comparison fits the listener, no condescending tone. If the skill is changed, re-measure with an A/B eval (section Reference — Eval).

Examples

• Positive: "explain wiki-sync.py --check to me" → engineer; run with the real repo, print exit code + file list ⇐ → observation "exit 3, 2 pages of drift flags" → TL;DR + seven sections with flowchart + sequence → remove print, git diff clean.
• Boundary/failure: "tell the boss why the report page is slow" but there is only prod log, cannot run locally → static explanation with a clear note, no code block/backtick, ≈ 700 words, ending with a recommendation; do not assert "always" when only one case has been seen.

Reference — You ARE ALLOWED to use tools to PROVE, not just read

The sentence "how does it run" must be proven by real runtime, not guessed from static reading. Tools in the Claude Code environment:

• Python: python3 -m pdb <file>, or breakpoint() temporarily, or debugpy. Cheaper: insert print(...)/logging at the point of interest and then run.
• Node/JS: node --inspect, console.trace(), debugger; temporarily, or console.log at the point of interest.
• Concept/tool (git, HTTP, SQL…): build the smallest case in a temp directory and actually run it (e.g. git init two branches modify the same line → merge → see a real conflict).
• Any: built-in /run (run the real app) and /verify (drive the flow, observe behavior). Run with specific input, observe real state at a specific line.

"This function probably returns X" is a guess. "I ran with input Y, set a breakpoint at line Z, observed state W" is fact. Always prioritize evidence — for EVERY listener. Listeners only change how evidence is PRESENTED, not whether evidence MUST be present.

Reference — Listener — what they care about, what they compare with, what tone

Group	They care about	Comparison drawn from	Tone
Engineer (default)	how it runs, architecture, trade-offs, maintenance	what they already know: "like a hash map but…", familiar patterns	precise, concise, uses the right terminology (missing terminology makes them feel looked down on)
Colleagues from other domains	impact on their work, what they need to know to coordinate	shared work, team process	practical, "what does this change for you"
Manager	impact, risk, time, cost, team capability	business results, personnel, budget	lead with impact, quantify when possible, close with the decision that needs to be made
Director	strategy, ROI, competitive advantage	the big picture, resource allocation	panoramic, short
Product Manager	value for users, priorities, scope	user stories, what to do / what to drop	by feature and user
Designer	experience, interaction flows, accessibility	screens, actions users see	by what users see and click
Undergraduate / graduate students	theory + application; graduate: nuances, edge cases, deeper consequences	the course's foundational knowledge	academic; terminology with brief context
Middle–high school students (≈12–17 years old)	clear causality, step by step	phones, social media, games, school	slightly friendly, no "trying too hard to be young"
Child ≈10 years old / grade 5	basic causality	school, sports, group assignments, video games	like a favorite teacher
5-year-old child (when "ELI5")	one easy-to-remember idea	toys, animals, candy, playground, picture books	fun, excited, very short sentences
Parents / older adults	understand without being looked down on	the technology they use, housework	respectful, clear, patient
Wife/husband/partner, friends	a story that's easy to follow	daily tasks, shared experience, popular culture	warm, conversational, can be humorous

Reference — Output framework (fixed — CORRECT ORDER, no section omitted)

Người nghe: <nhóm> — <điều họ quan tâm>
TL;DR: <MỘT câu "nó là gì"> + <MỘT phép so sánh với thứ người nghe đã biết>
    ↓
1. Tên gọi → 2. Nguồn gốc → 3. Lý do tồn tại → 4. Cơ chế hoạt động
→ 5. Trade-off → 6. Giới hạn → 7. Vị trí trong toàn bộ hệ thống
    ↓
So what: <điều này có nghĩa gì với CHÍNH người nghe — quyết định, hành động, hay điều cần nhớ>

The seven parts form one storyline: what it is called → where it comes from → why it must exist → how it runs → what was traded off to have it → what it CANNOT do → where it stands in the big picture. TL;DR + comparison opens the door (listeners immediately know what is being discussed); So what closes the door (listeners know what to take away). Purpose always comes before mechanism — no one cares about syntax before knowing what it exists to do.

The seven heading names stay the same for every listener (so the user can check the framework themselves); for non-technical listeners, everyday subtitles may be added, e.g. "5. Trade-off — what you gain, what you lose".

1. Name

The exact name (the designation used in code/docs), common synonyms/terms, and if the name is misleading (misnamed in essence), say so clearly right here.

2. Origin

Where it came from — which commit/PR/decision introduced it, where the idea was borrowed from (an existing library/paper/pattern or invented from scratch), which situation first created this need. If there is real evidence (git log, file Origin, ADR), cite it; do not speculate.

3. Reason for existing

What problem it solves; what happens without it — what becomes harder/breaks/must be done manually. It must be able to answer the question "remove this, who gets the headache first".

4. Mechanism of operation (+ system diagram & code diagram)

How it RUNS, at two levels:

• SYSTEM level — major components, who calls whom, where data goes, process/service/OS boundaries. Diagram: boxes + flow arrows.
• CODE level — the concrete execution path: which function calls which function, where state changes, which branch runs with the tested input. Diagram: call flow / sequence.

Step MUST be proven with real runtime — anchor to specific observations (line Z, state W), not generic documentation-like description.

5. Trade-off

To have this, what was traded off — choosing this branch means what is lost from the other branch (performance for simplicity, flexibility for safety, etc.). If there were other options considered/skipped, say clearly why they were dropped.

6. Limitations

What it CANNOT do, or where it performs poorly — scale ceiling, edge cases it does not cover, conditions under which it breaks. Different from Trade-off: Trade-off is "a deliberate trade at design time", Limitations is "the boundary where it stops, whether you want it or not".

7. Position in the entire system (+ flow summary diagram)

Where it plugs into the big picture — who calls it (upstream), what it calls/affects (downstream), which layer it sits in. Close with ONE summary diagram of the end-to-end flow: input → stages → output.

Reference — Depth by audience (seven parts are always enough — only the depth changes)

Audience	Step 4 Mechanism	Step 5–6 speak in	Diagram	Code / terminology	Length
Engineer, colleague, graduate student	both levels are enough; cite lines + observable state	performance, maintainability, edge cases	flowchart + sequence	cite real code; correct terminology	deep, but not rambling
Manager, Director, PM	system level only; runtime evidence says it in one sentence ("already test-ran: X → Y")	cost, risk, time, team effort	ONE box-arrow diagram	NO code block, NO backtick — write file names in lowercase	short — read in about 2 minutes (≈ 500 English words ≈ 700 Vietnamese words of text, excluding diagrams), close with a recommendation
Designer	the flow the user sees	experience, accessibility	screen flow	no code; UI terminology is fine	medium
Student, pupil	step-by-step cause and effect; abbreviated code level	"choose A then you lose B" with examples	one simple diagram	any term used is defined right at first mention	medium
Children, parents, spouse, friends	tell it as a story with comparisons	"what you gain, what you lose" in everyday life	optional, very simple	NO terminology, no raw logs; if you must use it, explain it immediately	short; even shorter for children

Language calibration

• Simple audience (children, non-technical, family): no jargon — at all; one idea per sentence; more concrete than abstract ("a server is like a waiter" rather than "a server handles client-server communication"); say "you" to feel closer.
• Technical audience (engineer, graduate student): use terminology correctly; put the words into the worth noting part — trade-offs, edge cases, design decisions; compare with what they already know; concise, respect what they already know.
• Business audience (manager, director, PM): lead with impact and results; quantify when possible; drop implementation details unless asked; frame it as a decision ("so we should…").

Reference — Example — the same thing, three listeners (opening + So what only)

Thing to explain: database index.

• 5-year-old — TL;DR: "An index is the table of contents of a giant book; it helps the computer find the right page really fast instead of flipping through every page." · So what: "Thanks to the table of contents, your game opens faster!"
• Manager — TL;DR: "An index is a structure that speeds up data lookups, like a book's table of contents; in exchange, every write gets a bit slower and uses extra space." · So what: "The reports page is slow because the orders table is missing an index; adding one takes about half a day of work, low risk — I suggest doing it this sprint."
• Engineer — TL;DR: "A B-tree index turns a lookup from O(n) full-table scan into O(log n), like an ordered hash map, but in exchange every INSERT/UPDATE has to update the tree." · So what: "Check EXPLAIN slow queries: if you see Seq Scan on a filter column, consider an index, but measure write amplification before adding it."

Reference — Diagram — two paths

• Default: mermaid inline — a mermaid block (flowchart for structure, sequenceDiagram for time-ordered flows). Fast, text-readable.
• Opt-in: HTML explainer — the user wants to KEEP / share / needs it to actually look good → render a page using /docs-site-macos (glass, light/dark toggle, print full-path, compact 13″ type scale); for diagrams call /diagram. Stand on the [[design-foundation]]foundation, do NOT spawn a new theme. Ask the user before producing a file, don't force it.

Reference — Eval — if you change the skill you must measure again (if the repo has harness/scripts/wikieval.py)

Learn from eli5: each case = one prompt + 4–5 checkable assertions; run the old and new versions of the skill on the SAME prompt and compare pass rates.

• Goldens: fdk/wiki/sources/evals/teach-me-*.md — three cases covering three listener types (engineer · manager · 5-year-old); deterministic asserts (order of the seven parts, no code for the manager, include a comparison for children…) + rubric for a judge.
• Run A/B: each version of the skill is answered prompt by prompt by an independent agent → collect into harness/evals/teach-me-ab-<ddmmyy>-<old|new>.json (map golden-id → answer) → python3 harness/scripts/wikieval.py --outputs <file>. The new version must not have a lower pass rate than the old one.

Origin

• Distilled from a user request 2026-07-16 (teach-me: 2 levels + the trio + summary, a diagram for each part; the skill knows how to use breakpoints/debugger). Grounded-runtime borrows the built-in philosophy /verify.
• Updated 2026-08-01 (feedback Rhein via /fdk): changed the "four parts" frame to the fixed seven steps — Name → Origin → Reason for existence → Mechanism of operation → Trade-off → Limitations → Position in the system. The content is runtime-driven + two diagrams are pushed into step 4; the flow summary diagram is pushed into step 7.
• Update 2026-09-11 (MERGED from dreambigou/eli5 @ a766623, MIT): add a step to identify the Audience (table of 12 groups by age/education/role/relationship, merged from four eli5 tables), open-close framework TL;DR + analogy → … → So what (from "what → analogy → details → so what"), seven-part depth table by audience, language calibration for three groups, examples of the same thing for three audiences, rules "no condescending tone / simplify without saying anything false / no backticks for non-technical people", and the A/B eval loop (eli5 run-evals.py --a/--b → reuse wikieval.py + goldens instead of copying the runner). Different from eli5: the default audience is engineers (not a 5-year-old), the seven steps stay the same, runtime evidence is still mandatory for every audience.
  • First A/B (3 cases, each version answered by an independent agent, outputs in harness/evals/teach-me-ab-110926-{old,new}.json): old deterministic assertions 8/13 → new 13/13; blind judge on 4 criteria old 6/12 → new 9/12. The manager case still fails in the new version because it is long (~718 syllables) and one evidence sentence overstates what was observed → add a length threshold calculated by Vietnamese syllables + an evidence compression rule (not yet re-measured after these two rules).
• Absorbed via /propose → 160726-teach-me-skill, task T-260716-01.
• Commit: (filled by verify-before-commit)