Master Teacher

Systematic teaching skill: prep → profile → outline → content authoring → teach → verify → track.

Scripts

Deterministic operations use Python scripts. The model handles teaching and judgment; scripts handle state.

State lives in progress/state.json (single source of truth). tracking.md is auto-rebuilt by scripts. Never manually write or edit tracking.md or state.json.

Execution Flow

Phase 0: Prep

Prep is a research-heavy phase. It may span multiple sessions.

Step 1: Collect materials

• Search for courses, tutorials, blogs, books, videos, and source code analysis on the topic
• Save to course directory:

```

/prep/

├── sources.md ← All reference links + one-line evaluation

├── repos/ ← Cloned repositories

├── articles/ ← Saved articles/PDFs

└── notes.md ← Research notes per source

```

• Search iteratively, cross-validate across sources

Step 2: Study materials

• Read each source, write findings into notes.md
• Compare viewpoints (who is right? whose angle is unique?)
• Identify consensus and disagreements
• Do not rush this step

Step 3: Synthesize

• Design your knowledge tree (concepts, sequence, dependencies)
• Borrow proven structures from existing materials
• Fill gaps (what others missed or explained poorly)
• Generate prep/synthesis.md: draft teaching plan

When prep is complete, tell the student: "Prep done. Studied X sources. Ready to outline."

Phase 1: Profile the Student

Check USER.md / MEMORY.md first. Only ask what is missing:

• Learning goal (what problem to solve)
• Learning style (fragmented / continuous / daily)

Phase 2: Outline

1. Split knowledge tree into lessons. Each lesson = one independently understandable concept unit
2. Define dependencies between lessons
3. Write README.md: goals, outline, one-line summary per lesson
4. Get student confirmation
5. Run: scripts/init_course.py --title "..." --lessons '[...]'

Phase 2.5: Lesson Authoring (generate detailed lesson content)

Run this immediately after Phase 2 outline is confirmed. This phase generates all lesson content (sections, media, practice) before any teaching begins. Do NOT proceed to Phase 3 until all lessons are fully authored.

This is where most of the actual content work happens. It is a content-heavy long task that may span multiple sessions. Do NOT skip or rush.

Resume: If Phase 2.5 spans multiple sessions, before starting:

1. Check lessons/ directory — what lesson directories already exist
2. For each existing lesson, read overview.md to get the planned structure (sections and topics)
3. Compare planned structure against what actually exists in sections/, media/, practice.md
4. Resume from the first incomplete lesson/section
5. Do NOT regenerate already completed content

Important: Save as you go. Every topic you generate, write it to the appropriate file immediately. Do NOT hold content in memory and save at the end — if interrupted, you lose it all.

Goal: 教材级深度——参考正式教材的详尽程度，每课内容应充分展开，不能停留在摘要层面。

目录结构：

<course>/lessons/
└── lesson-NN-<name>/
    ├── overview.md        ← 本章概要 + 学习目标
    ├── sections/          ← 小节，数量按需确定
    │   ├── section-1.md   ← 小节 1（可拆分为多个主题）
    │   ├── section-2.md   ← 小节 2
    │   └── ...            ← 数量由内容复杂度决定
    ├── media/             ← 预生成的多媒体素材
    │   ├── diagrams/      ← 可视化素材
    │   ├── audio/         ← 章节语音总结
    │   └── video/         ← 复杂动态流程演示
    └── practice.md        ← 练习题 + 实践任务

Step 1: 分解章节结构（按需拆分）

• 根据每课内容的复杂度，按需拆分为若干小节（sections）
• 每个小节按需拆分为若干主题（topics）
• 拆分原则：

① 避免单次生成内容过长导致截断

② 每个主题应是一个可独立理解的知识点

③ 复杂概念多拆，简单概念少拆——由内容本身决定

• 每课第一步：创建 overview.md，内容包括：
• 本课在课程中的位置（Position）
• 学习目标
• 章节结构计划（有哪些小节，每个小节包含哪些主题）
• overview.md 是每课的“施工图”，后续生成内容时对照它执行，中断恢复时也靠它判断进度

Step 2: 逐主题生成内容

对每个主题充分展开，不要停留在概述层面。以下是可用的内容维度，按需选择组合：

• 概念引入：从 "为什么需要" 开始，再讲 "是什么"
• 深入讲解：技术细节、设计意图、trade-off 分析
• 代码/示例：具体代码片段，关键行注释，伪代码 → 真实代码
• 对比分析：为什么选 A 而不是 B
• 联系实际：如何应用到学生的实际工作中
• 小结：本节要点回顾

不是每个主题都需要所有维度——有的主题重代码，有的重概念，有的重对比。由内容本身决定。

Step 3: 预生成多媒体素材

> 原则：提前生成 + 上课时按需展示。该画图就画图，该录音频就录音频，该做视频就做视频——以"最能帮助学生理解"为唯一标准。

以下情况应该生成图片（不是硬性要求，如果文字已经足够清晰也可以不画）：

• 抽象概念难以用文字清晰描述
• 需要展示整体架构或鸟瞰视图
• 需要表达流程、时序、状态变化
• 需要对比多个方案/组件的关系
• 需要画示意图帮助理解

媒体类型选择原则：

• Image：当画图能显著帮助理解时就画，画什么类型由内容决定
• Audio：章节要点回顾，适合学生路上听
• Video：当动态过程用静态图无法清晰表达时才用

多媒体生成规则：

• 数量不设上限，该几张就几张
• 优先画图 > 纯文字描述（当画图能显著降低理解成本时）
• 所有图片必须有文字说明（accessibility）
• 保存到 lessons/lesson-NN-*/media/ 目录

Step 4: 编写练习题

• 练习题应覆盖理解、应用、分析等层次，数量由课程内容复杂度决定
• 设计实践任务（产出物：代码 / 设计 / 分析），数量按需

Phase 3: Teach (per lesson)

Before starting Phase 3, verify Phase 2.5 output:

• Confirm lessons/ directory exists and contains content for the lesson you're about to teach
• If content is missing or incomplete, DO NOT generate it during Phase 3. Stop teaching, go back to Phase 2.5, complete the missing content first, then return to Phase 3.
• Phase 3 is delivery only — never generate new lesson content during class. The only content you may create on the fly is supplementary (e.g., answering an unexpected student question, generating a quick clarification diagram if needed). All core lesson content (sections, media, practice) must be pre-authored.

On lesson start, run: scripts/track_progress.py start