teach-eli5 v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/29bff3feec982586.

---
name: teach-eli5
description: >
  像给完全不懂的小白讲清楚一件事。用户输入 /eli5 <主题> 或要求"用大白话/给外行讲明白
  /做个看图就懂的教学页"时触发。采用 mattpocock teach 方法论——以「学习目标(MISSION)」锚定、
  「最近发展区(ZPD)」选材、每课一个自包含可打印的精美 HTML、复用组件库(assets)、沉淀术语表( glossary )与
  学习记录( learning-records )，把复杂主题拆成"图多字少、类比先行"的小白友好教学页。
  适用: 概念科普、技术原理给非技术人员、产品/功能讲解、知识卡片化教学。
argument-hint: "想搞懂什么？一句话说出你的场景"
user_invocable: true
version: "1.0.0"
---

# teach-eli5 —— 给小白讲明白的教学引擎

把任何复杂主题，拆成「图多、字少、类比先行」的自包含教学 HTML，让零基础的人看图就能懂。
本技能融合了 mattpocock `teach` 的方法论（状态化、以目标锚定、最小可教学单元、复用组件、沉淀术语）与 eli5 的小白约束（不用术语、先类比、后精确）。

> 哲学一句话：**先让用户"啊哈"一下，再让他"记住"。** 前者靠类比和图，后者靠重复和可回看的精美页面。

## 教学工作区（状态保存位置）

把**当前目录**当作教学工作区。用户的学习状态用几个文件持久化，跨会话累积：

- `MISSION.md`：用户**为什么**想懂这个主题（所有教学决策的锚点）。格式见 [references/MISSION-FORMAT.md](./references/MISSION-FORMAT.md)。
- `./lessons/*.html`：每**一课**是一个自包含 HTML 教学页。这是教学的主单元。命名 `0001-<slug>.html` 递增。
- `./assets/`：**可复用组件**（共享样式表、类比卡片模板、图示 helper、quiz widget）。见 [Assets](#assets)。
- `./references/glossary.md`：术语表，本工作区的"官方语言"。一旦建立，每课都遵守。
- `./learning-records/*.md`：学习记录（类似软件开发的 ADR），记录用户已搞懂的非显然结论。命名 `0001-<slug>.md` 递增。
- `NOTES.md`：你的草稿本，记用户偏好与工作备忘。

## 流程

### 第 0 步：定锚（Mission）

如果用户没说清为什么想懂这个，或 `MISSION.md` 还没写，**先访谈**再动笔。
含糊的目标会产出抽象的课。用 [MISSION-FORMAT](./references/MISSION-FORMAT.md) 的格式记录。
用户的"想搞懂"常是表层，要往下挖一层真实诉求（"想给客户解释""想面试""想修自家水管"）。

> 若用户只是随口要一个一次性讲解（如 `/eli5 黑洞`），可直接进入第 2 步产单课，不强制建全工作区；但**仍建议**顺手写一句 MISSION。

### 第 1 步：判定起点（ZPD，最近发展区）

每课都要让用户感到"刚好有点挑战"。读 `learning-records/` 和 `NOTES.md`，判断：

- 用户已知什么（别重复教）
- 当前最该懂的"下一个最小知识点"是什么
- 这个知识点是否直接服务于 MISSION

小白优先用**生活类比**搭桥，再引入精确概念。例子：讲"API"→先"餐厅里服务员帮你传菜"，再"程序之间传数据的约定"。

### 第 2 步：产出一课（Lesson = 自包含 HTML）

每一课是一个 `./lessons/000N-<slug>.html`，**小白友好**是硬约束：

1. **图多字少**：核心机制用 SVG 图示 / 类比图表达，正文克制。每屏只讲一件事。
2. **先类比，后精确**：先用生活类比让人"啊哈"，再给一句精确表述（精确句可折叠或放最后）。
3. **禁用行话**（除非已进 glossary 且本页首次出现时就地解释）。用词对齐 `references/glossary.md`。
4. **一个可带走的小收获**：每课结束时用户应能复述一个要点。
5. **Tufte 式排版**：干净、可读、留白足；这是用户会回头复习的页，不是一次性聊天。
6. **紧扣 MISSION**：说明"懂这个对你那个目标有什么用"。
7. **一句提醒**：页尾提示"有不懂的随时问，我可以接着讲"——你是老师，不是一次性生成器。

版面规范见 [references/LESSON-FORMAT.md](./references/LESSON-FORMAT.md)。每课链接到其它课与 reference 文档（HTML 锚点）。
如环境允许，用 CLI 命令打开该 HTML 给用户看。

### 第 3 步：沉淀（每次产课顺手做）

- **术语**：出现且用户已理解的词，加进 `references/glossary.md`（定义一两句，列出"避免混用的说法"）。
- **学习记录**：用户展现了真理解（答对了 / 说清了 / 纠正了误区），写一条 `./learning-records/000N-<slug>.md`。仅记"决策级洞见"，不写流水账。格式见 [references/LEARNING-RECORD-FORMAT.md](./references/LEARNING-RECORD-FORMAT.md)。
- **复用组件**：本课用到的新可复用部件（图示模板、quiz），写成 `./assets/` 下的组件并链接，别内联到单课里（`assets/base.css` 是首个该有的共享样式）。

### 第 4 步：难度与复习

- **流利度 ≠ 记住**：当堂能答给人"学会了"的错觉，**长期留存**才是目标。
- 用「合意困难」设计：回忆练习（合上页复述）、间隔（隔几天再出一题）、交错（相关小主题混着练）。
- 小白场景下，**间隔复述 + 一图流总结卡**比测验更有效，优先给"一张图带走"的复习页。

## Assets（复用组件库）

课由 `./assets/` 里的**可复用组件**拼成。复用是默认，不是例外。

- 动手写课前先读 `./assets/`，用已有的组件。
- 需要新且可复用的东西，写成 `./assets/` 下的组件并链接；绝不把未来会复用的代码内联进单课。
- 第一个该有的组件是共享样式表 `./assets/base.css`：每课都链它，让所有课像"一门课"而非一堆散页。

## 约束与红线

- **不堆砌术语**：小白要的是"懂"，不是"显得专业"。一个概念没用类比搭桥就给精确定义 = 失败。
- **不信参数记忆**：需要事实/数据时，优先查 `references/` 与高信任外部资源并标注来源，不凭记忆编造数字。
- **不产长文**：单课控制在"几分钟内能看完"。零基础的工做记忆很小，必须守在里头。
- **图优先**：能画图说清的，不用段落。SVG 内联，自包含、可离线打开。
- **中文无乱码**：写入文件禁用 Box Drawing 等 Unicode 装饰字符（防 U+FFFD），用纯 ASCII 替（树形 `|--`、箭头 `->`）。

## 与 mattpocock teach 的关系

本技能取其**骨架**（MISSION 锚定、ZPD 选材、课时自包含 HTML、assets 复用、glossary/learning-records 沉淀），
并叠加 eli5 的**小白约束**（图多字少、类比先行、禁行话、一图流复习）。
原 `teach` 面向"在 workspace 里长期学一门技能"（如瑜伽、Rust），本技能面向"把一件事给外行讲明白"，
因此略去了社区/智慧(community)分支，强化可视化与单页可懂性。