lesson-generator

Files (7)

• README.md
• SKILL.md
• engagement-patterns.md
• module-0.2-outline.md · examples/
• module-0.3-outline.md · examples/
• interactive-templates.md
• video-index.md

SKILL.md (first lines)

# Lesson Generator

A recursive curriculum generation and revision system that operates at three zoom levels:

```
Course (elicitation → curriculum brief → arc map)
    ↓
Arc (theme + context → module breakdown → publication checkpoints)
    ↓
Module Lesson (spec → belt system → executable notebook)

+ Revision Mode (update any artifact with cascade awareness)
```

---

## Fractal Concept Loop (Core Structural Principle)

**Every concept, at every zoom level, runs the same four-stage loop: DO → NOTICE → CODE → NAME.**

This is not a narrative suggestion — it's a structural requirement. The loop applies recursively: courses are made of arcs, arcs of modules, modules of sections, sections of **concept primitives** — and every concept primitive gets the full cycle.

### The Loop

| Stage | What Happens | Modality |
|-------|-------------|----------|
| **DO** | Experience it. Hear it, see it, interact with it. No labels yet. See `scaffold-pass` for the **designed failure variant**. | All available senses |
| **NOTICE** | Guided observation. "What did you notice?" Pattern recognition prompts. | Reflective |
| **CODE** | Build/modify/express. Change parameters, break it, make something with it. | Tactile/code |
| **NAME** | Now formalize. Give it its proper name, connect to theory, define it. | Symbolic |

### Concept Primitives

A **concept primitive** is the smallest unit of understanding where confusion is possible. Not "what has a name" but "what could go wrong in someone's head."

**Decomposition heuristic**: Keep asking "could someone be confused about a piece of this?" until the answer is no. That's your base case.

**Examples:**
- "A whole step skips one key" — primitive (you could think it means skip two)
- "E→F has no black key between them" — primitive (you could assume all white keys are equally spaced)
- "The W-W-H-W-W-W-H pattern defines major" — NOT primitive. Decompose into: what W means, what H means, why that specific sequence, what happens if you change one
- "Multiplying by a weight makes something count more" — primitive
- "Weights should sum to 1" — primitive (you could think any weights work)
- "A weighted average" — compound, built from the two primitives above

### Decomposition in Outlines

Before planning the loop for a section, **decompose** it into confusion-primitives:

```
Section: Major Scales
  Decomposition:
    - "notes have distances between them" (foundational, may already be earned)
    - "some distances are bigger than others" (half vs whole)
    - "a specific distance pattern makes it sound 'major'" (the sequence)
    - "the same pattern starting on any note gives you a new major scale" (transposition)

  Each primitive → DO → NOTICE → CODE → NAME
  Each primitive → sensory projection (which modalities?)
  Primitives chain: each one builds on the previous
```

**Skip mechanism**: If a primitive is already earned from a prior module, reference it and move on. No redundant loops. Track earned primitives across modules the same way jargon-earning is tracked.

### Sensory Projection Matrix

Every concept primitive must be projected into **at least 2 available modalities**. Plan this explicitly in the outline:

| Modality | Music Implementation | Math/ML Implementation |
|----------|---------------------|----------------------|
| **Visual** | SVG diagrams, p5.js waveforms, circle/keyboard viz, animations | Plots, geometric diagrams, FuncAnimation, Plotly 3D |
| **Auditory** | Tone.js synthesis, TidalCycles patterns, Strudel embeds, audio playback | Data sonification, audio feedback on convergence, "sound of a distribution" |
| **Tactile/Code** | Live coding, keyboard interaction, sliders, parameter knobs | ipywidgets, parameter tuning, "build a toy" exercises, code cells |

**Per-primitive planning format:**

```
Primitive: "some distances are bigger than others"
  DO:    hear C→D then hear E→F (auditory). see gaps on keyboard SVG (visual)
  NOTICE: "one jump skips a key, the other doesn't. what's different?"
  CODE:  slider for step size in semitones, hear + see the result (tactile + auditory + visual)
  NAME:  "whole step = 2 semitones. half step = 1 semitone."
  Modalities: auditory ✓ visual ✓ tactile ✓
```

### Fractal Recursion Across Zoom Levels

The loop applies at every level of the curriculum:

| Level | Unit | Loop Application |
|-------|------|-----------------|
| **Course** | Arc | Each arc has a DO (taste demo), NOTICE (patterns), CODE (build), NAME (formalize) |
| **Arc** | Module | Each module motivates → implements → verifies → names |
| **Module** | Section | Each section opens with experience, ends with formalization |
| **Section** | Concept primitive | Each primitive gets the full DO → NOTICE → CODE → NAME cycle |

The section level is where the loop is **mandatory and explicit**. Higher levels emerge naturally from well-structured sections.

---

## Outline-First Workflow (Module Generation)

**Critical**: Don't generate notebooks directly from arc syllabi. The arc syllabus is too high-level. Instead, use an **outline-first workflow**:

```
Arc syllabus (high-level spec)
    ↓
Riff with user (war stories, scope, conceptual ordering)
    ↓
Detailed narrative outline (ready-to-generate artifact)
    ↓
User approves/tweaks outline
    ↓
Generate notebook from outline
```

### What Makes an Outline "Ready to Generate"

A ready outline has:

From Peleke/brunnr, MIT.

More from Peleke/brunnr