engagement-pass

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# Engagement Pass

A retrofit skill that analyzes existing Jupyter notebooks and adds interactive engagement elements without changing the narrative flow or learning sequence.

**When to use**: On notebooks that are already written and working but are purely static (matplotlib only, no widgets, no videos, no interactive plots).

**When NOT to use**: During initial notebook generation — the `lesson-generator` skill now includes engagement patterns (sections 13-18) and should generate with them from the start.

---

## Trigger Detection

Activate on:
- "Add engagement to [notebook]"
- "Make [notebook] interactive"
- "Retrofit [notebook]"
- "Engagement pass on [notebook]"
- "Add interactive elements to [notebook]"
- "This notebook needs more dopamine"

---

## Process

### Step 1: Analyze

Read the target notebook and identify enhancement opportunities:

**Scan for**:
| What to Find | Enhancement Type | Priority |
|-------------|-----------------|----------|
| Static matplotlib scatter plots with meaningful per-point data | Plotly conversion | High |
| 3D matplotlib surface plots | Plotly 3D conversion | High |
| Missing concept map after imports | Arc progress map | High |
| Concept introductions (interludes, theory sections) | Video embed opportunity | High |
| Parameter explorations ("try changing X") | Widget (ipywidgets) | Medium |
| Simulations or Monte Carlo sections | Button-triggered widget | Medium |
| Time-series / convergence / updating sections | FuncAnimation | Medium |
| Static bar charts comparing categories | Plotly bar with hover | Medium |
| Exercise sections without a "build" component | "Build a toy" candidate | High |
| Every single matplotlib plot | NOT a conversion candidate | N/A |

**Output**: A concrete enhancement list with cell numbers and descriptions.

### Step 2: Prioritize

Not everything should be converted. Apply the engagement budget:

**High priority** (do first):
1. Arc progress concept map (after imports) — every notebook needs one
2. 1-2 key Plotly conversions where hover/interaction genuinely helps
3. 1 strategic video embed at a concept introduction point

**Medium priority** (do if budget allows):
4. Widget for parameter exploration
5. Animation for a dynamic concept
6. Additional Plotly conversions

**Low priority** (skip unless specifically requested):
7. Converting every matplotlib plot to Plotly
8. Adding widgets to sections where the static version is clear enough
9. Multiple animations (expensive to render)

**Budget limits per notebook**:
- Max 1 concept map
- Max 3 video embeds
- Max 4 Plotly conversions
- Max 3 widgets
- Max 2 animations
- At least 1 "build a toy" exercise

### Step 3: Apply

Insert enhancements using templates from `lesson-generator/interactive-templates.md`.

**For each enhancement**:

#### Concept Map
1. Add engagement imports to the imports cell (Cell 2)
2. Insert `arc_progress_map()` call as a new cell after imports
3. Use `ARC_0_MODULES` list and set `current_module` appropriately

#### Video Embed
1. Identify the target section from `lesson-generator/video-index.md`
2. Create a new markdown cell with contextual intro (1-2 sentences)
3. Add code cell with `embed_video(video_id, title, context)`
4. Place AFTER the reader has worked through the concept, not before

#### Plotly Conversion
1. Read the existing matplotlib cell
2. Determine what hover data would be useful
3. Replace with equivalent Plotly code using templates
4. Keep the same color palette and visual style
5. Remove the old matplotlib cell (don't leave both)

#### Widget Addition
1. Identify the parameter(s) the reader should explore
2. Choose widget type: `@interact` for simple sweeps, button for stochastic processes
3. Add the widget cell after the static version
4. Include a "What to notice" comment guiding exploration

#### Animation
1. Show the static/final result first (existing cell)
2. Add animation cell after with `FuncAnimation` → `HTML(anim.to_jshtml())`
3. Include frame counter and running metrics in the animation

#### "Build a Toy" Exercise
1. Place in the Exercises section
2. Provide scenario, components, task, success criteria, extensions
3. Include starter code and a working solution in a separate cell
4. The toy must be interactive (widgets + plotly/matplotlib)

### Step 4: Validate

After applying enhancements:

- [ ] All cells run sequentially without error
- [ ] Story flow is unchanged — enhancements clarify, don't distract
- [ ] No widget overload (check budget limits)

From Peleke/brunnr, MIT.

More from Peleke/brunnr