Teach Me

# Teaching Examples

How the /teach-me agent should behave in each mode.

## Interactive Mode Examples

### Example 1: Beginner asks about async/await

**User**: `/teach-me async await in javascript`

**Agent Phase 0A — STUDY (silent)**:
> Topic: async/await in JavaScript
> Confidence tier: TIER 1 (stable JS feature since ES2017)
> Even Tier 1 topics need study for PEDAGOGY — how to teach it best.
> 
> web_search: "javascript async await common mistakes 2025"
> web_search: "async await best practices modern javascript"
> web_search: "site:ocw.mit.edu asynchronous programming" → no direct hit,
>   but 6.031 Software Construction covers concurrency concepts
> 
> DEEP READ results:
> - Top-level await is now standard in ES modules
> - Promise.allSettled preferred over Promise.all in many cases
> - Common mistakes: forgetting await (silent bugs), try/catch placement,
>   sequential await when parallel is possible
> 
> Comprehension check:
> □ Core concepts: callbacks → promises → async/await → error handling → parallelism ✓
> □ What's hard: the mental model shift from "do this then that" to "start this, come back later" ✓
> □ Misconceptions: "await pauses the whole program" (it doesn't — only the async function) ✓

**Agent Phase 0B — PREPARE (silent)**:
> Concept map:
> 1. Callback hell problem → analogy: nested Russian dolls
> 2. Promises = claim ticket → analogy: restaurant buzzer
> 3. async/await = syntactic sugar → "same promises, looks like normal code"
> 4. Error handling → try/catch wraps the await
> 5. Parallelism → Promise.all for independent operations
> 
> For each: analogy ready, simple example ready, common mistake ready
> Both tracks ready (conceptual for beginners, code-heavy for experienced)
> Anticipated: learner knows callbacks → can anchor on that

**Agent (Phase 1 — Orient)**:
> Before we dive in — how comfortable are you with JavaScript? Specifically, have you worked with callbacks or Promises before, or is this your first time dealing with async code?

**User**: I know callbacks but promises confuse me

**Agent (Phase 2 — Build, using prepared concept map)**:
> Perfect, callbacks are exactly the right starting point. Let me build from there.
>
> You know how callbacks work — you pass a function to run "later":
>
> ```javascript
> readFile('data.txt', function(err, data) {
>   console.log(data);
> });
> ```
>
> The problem is when you need to do three things in sequence:
>
> ```javascript
> readFile('a.txt', function(err, a) {
>   readFile('b.txt', function(err, b) {
>     readFile('c.txt', function(err, c) {
>       console.log(a, b, c); // callback hell
>     });
>   });
> });
> ```
>
> That nesting gets ugly fast. A Promise is just a way to flatten this. Think of it like a **claim ticket at a restaurant** — you order food (start an async operation), get a ticket (Promise), and the ticket says "I'll let you know when your food is ready."
>
> ```javascript
> readFile('a.txt')           // returns a Promise (claim ticket)
>   .then(a => readFile('b.txt'))  // when ready, start next
>   .then(b => readFile('c.txt'))  // chain them flat
>   .then(c => console.log(c));    // no nesting!
> ```
>
> See how the nesting disappeared? Same logic, flat chain.
>
> Now — async/await is just *syntax sugar* on top of this. Same Promises underneath, but it LOOKS like normal synchronous code:
>
> ```javascript
> const a = await readFile('a.txt');
> const b = await readFile('b.txt');
> const c = await readFile('c.txt');
> console.log(a, b, c);
> ```
>
> Quick check: in the await version, does `b` start reading before or after `a` finishes?

Note the pattern:
- Gauged level from their response
- Anchored to what they know (callbacks)
- Showed the problem first (callback hell)
- Used an analogy (claim ticket)
- Progressive complexity (callbacks → promises → async/await)
- Ended with a comprehension question

### Example 2: Advanced user asks about Playwright

**User**: `/teach-me playwright test fixtures, I'm coming from Jest`

**Agent Phase 0A — STUDY (silent)**:
> Topic: Playwright test fixtures
> Confidence tier: TIER 2 (framework-specific, evolves between versions)
> MUST search and READ before teaching — can't rely on training data.
>
> web_search: "playwright test fixtures documentation"
> web_fetch: https://playwright.dev/docs/test-fixtures → DEEP READ:
>   - Fixtures are functions that set up/tear down for each test
>   - Worker-scoped fixtures share state across tests in a worker
>   - Custom fixtures extend the base test object
>   - Fixture types: test-scoped (per test) vs worker-scoped (per worker)
> web_search: "playwright fixtures vs jest beforeEach"
> web_search: "playwright custom fixtures example 2025"
>
> Comprehension check:
> □ Core concepts: built-in fixtures, custom fixtures, scoping, composition ✓
> □ What's hard: mental model shift from "global setup" to "dependency declaration" ✓
> □ Misconception: "fixtures are just beforeEach with extra steps" (no — they're DI) ✓

**Agent Phase 0B — PREPARE (silent)**:
> Concept map:
> 1. Jest comparison → analogy: dependency injection vs global setup
> 2. Built-in fixtures (page, context, browser) → show what you get for free
> 3. Custom fixtures → show how to extend
> 4. Scoping (test vs worker) → analogy: fresh towel per guest vs shared pool towel
> Checkpoint: "Why would you use a worker-scoped fixture instead of test-scoped?"
> Anticipated: They'll ask about beforeEach — have comparison ready

**Agent (Phase 1 — Orient, fast since they're advanced)**:
> Coming from Jest, you already know `beforeEach`/`afterEach` for setup and teardown. Playwright fixtures are that concept on steroids.
>
> The mental model shift: in Jest, setup code runs for every test in the file whether it needs it or not. Playwright fixtures are **declared as dependencies** — a test only gets what it asks for.
>
> ```typescript
> // Jest way — EVERY test gets a browser, even if it doesn't need one
> let browser;
> beforeAll(async () => { browser = await chromium.launch(); });
> afterAll(async () => { await browser.close(); });
>
> // Playwright way — only tests that ASK for 'page' get one
> test('needs a page', async ({ page }) => { /* gets a fresh page */ });
> test('no page needed', async ({}) => { /* no browser launched */ });
> ```
>
> Think of it like **dependency injection** vs **global setup**. Each test declares its dependencies in the argument list, and Playwright provides them — fresh, isolated, and automatically torn down.
>
> What happens when you want a fixture that's shared across tests — like a logged-in user? That's where it gets interesting. Want to dig into custom fixtures, or should we cover scoping first?

Note the pattern:
- Phase 0 verified the fixture API is current before teaching
- No level assessment needed (they said "coming from Jest")
- Immediately used contrast (Jest vs Playwright)
- Mental model, not just API docs
- Analogy (dependency injection)
- Offered a choice for next direction

### Example 3: Phase 0 prevents a mistake

**User**: `/teach-me how to set up authentication in Next.js`

**Agent (Phase 0 — silent)**:
> Topic: Next.js authentication
> Confidence tier: TIER 3 — MUST SEARCH. Auth approaches in Next.js change
> frequently (App Router vs Pages Router, server components, middleware patterns).
>
> web_search: "next.js authentication 2025 recommended"
> web_search: "next.js auth.js nextauth v5"
> web_fetch: https://nextjs.org/docs/app/building-your-application/authentication
> web_search: "next.js middleware authentication pattern"
>
> CRITICAL FINDING: Training data says "use next-auth" but the library
> has been renamed to "Auth.js" and v5 has a completely different API.
> The new approach uses middleware + server components, not API routes.
> If I taught from memory, I'd show deprecated patterns.
>
> Knowledge base updated with current Auth.js v5 API.

**Agent (Phase 1)**:
> Next.js auth has changed a lot recently — the recommended approach
> now uses Auth.js (formerly NextAuth) v5, which works quite differently
> from the older version you might have seen in tutorials online.
>
> Before we dive in — are you using the App Router or the Pages Router?
> And have you worked with any auth library before (Passport, Firebase Auth, etc.)?

Note the pattern:
- Phase 0 caught that training data was OUTDATED
- Agent proactively warned the learner about stale tutorials
- Didn't teach the deprecated pattern
- Asked clarifying questions to further narrow the approach

### Example 4: OCW-powered teaching (academic topic)

**User**: `/teach-me graph algorithms`

**Agent (Phase 0 — silent)**:
> Topic: Graph algorithms
> Confidence tier: TIER 1 (stable CS fundamental) — but pedagogy matters,
> so I should find the BEST teaching approach.
>
> web_search: "site:ocw.mit.edu graph algorithms"
> Found: MIT 6.006 (Intro to Algorithms) covers BFS, DFS, shortest paths
>        MIT 6.046J covers more advanced graph algorithms
> web_fetch: MIT 6.006 syllabus — topic order is:
>   Lecture 9: BFS → Lecture 10: DFS → Lecture 11: Weighted Shortest Paths
>   (Dijkstra) → Lecture 12: Bellman-Ford
> web_fetch: MIT 6.006 Lecture 9 notes (BFS)
>
> Key insight from MIT's approach: They teach BFS BEFORE DFS because BFS
> naturally leads to shortest paths, which is more intuitive for beginners.
> Most online tutorials do it the other way around.
>
> web_search: "graph algorithms common mistakes beginners"
> Found: Forgetting visited set, confusing directed/undirected, stack vs
> queue confusion between BFS/DFS
>
> Knowledge base ready. Will follow MIT's BFS-first approach.

**Agent (Phase 1)**:
> Graph algorithms are one of the most powerful tools in CS — MIT 
> dedicates several lectures to them in their intro algorithms course,
> and I'll use a similar approach here because it builds up really 
> naturally.
> 
> Quick question before we start: do you know what a graph is in CS
> terms (nodes and edges), or should we start from scratch?

Note the pattern:
- Searched OCW for the academically-proven teaching order
- Discovered MIT teaches BFS before DFS (non-obvious, pedagogically sound)
- Used MIT's structure as the foundation but will teach conversationally
- Credited the approach without being stiff about it
- Still checked for common mistakes (practical, not just academic)

### Example 5: OCW relevance check (old course, still valid)

**User**: `/teach-me linear algebra`

**Agent (Phase 0 — silent)**:
> Topic: Linear algebra
> Confidence tier: TIER 1 (pure math, stable forever)
> 
> web_search: "site:ocw.mit.edu linear algebra 18.06"
> Found: MIT 18.06 by Gilbert Strang — legendary course, multiple
> semesters available (2005, 2010, Spring 2023, Fall 2024)
>
> RELEVANCE CHECK:
> - Is the math outdated? NO — linear algebra hasn't changed.
> - Is there a newer offering? YES — Fall 2024 exists.
> - Does the older version still work? YES — Strang's 2005 lectures
>   are considered among the best ever recorded.
> - Prefer newest for lecture notes, but older videos are actually
>   better taught (this is well-known in the math community).
>
> web_fetch: MIT 18.06 syllabus (newest version)
> Topic order: Geometry of linear equations → Elimination →
> Matrix operations → Factorizations → Vector spaces → Eigenvalues
>
> Also found: MIT 18.065 (Matrix Methods in Data Analysis) for
> ML applications — good "what's next" recommendation.

Note the pattern:
- Found multiple OCW semesters, compared them
- Verified the content is still relevant (math doesn't expire)
- Noted that older video lectures are actually preferred (nuanced judgment)
- Found a "next step" course recommendation

---

## Course Builder Mode Examples

### Example: Course from docs

**User**: `/teach-me playwright --course --format=html from https://playwright.dev/docs/intro`

**Agent flow**:
1. Read `references/course-builder.md`
2. Read `references/format-html-interactive.md`
3. Crawl the docs site
4. Analyze: structure, concepts, gaps
5. Design outline with progressive project
6. Write full tutorials applying teaching methodology
7. Output as single interactive HTML file
8. Quality check before delivering

### Example: Course from repo

**User**: `/teach-me this repo --course --format=md`

**Agent flow**:
1. Read `references/course-builder.md`
2. Read `references/format-markdown.md`
3. Analyze repo: files, architecture, concepts
4. Design outline
5. Write tutorials referencing real files/code
6. Output as .md files + INDEX.md

---

## Docs-Sourced Teaching (No Course)

### Example: Interactive teaching from docs

**User**: `/teach-me react hooks from https://react.dev`

**Agent**: Does NOT build a course. Instead:
1. Crawls React docs on hooks
2. Identifies the key concepts and their best examples
3. Starts an interactive teaching session USING the docs as material
4. References specific docs pages as "further reading"
5. Fills gaps the docs leave (e.g., connects useState and useEffect)

**Agent (first message)**:
> I've looked through the React docs on hooks. Before we start — have you used class components before, or are you starting fresh with React?
>
> [interactive teaching begins, using examples from the docs but explaining them better than the docs do]

---

## Level Adaptation Examples

### Same Topic, Three Levels

**Topic**: "How does HTTPS work?"

**Novice** (uses everyday analogy):
> Imagine sending a postcard vs. a letter in a sealed envelope. HTTP is the postcard — anyone who handles it can read it. HTTPS is the sealed envelope — only the person you're sending it to can open it.

**Intermediate** (uses technical analogy):
> HTTPS wraps HTTP in TLS encryption. Think of it as a tunnel — the data inside (your HTTP request) is the same, but the tunnel prevents anyone from seeing it in transit. The interesting part is HOW the tunnel gets established — that's the TLS handshake...

**Advanced** (goes straight to mechanics):
> The TLS 1.3 handshake is a 1-RTT process. Client sends ClientHello with supported cipher suites and key shares. Server responds with ServerHello, its certificate, and the finished message — all in one round trip. The key exchange uses ECDHE, and the certificate is verified against the system's CA trust store. Want to dig into how certificate pinning changes this, or how 0-RTT resumption works?