microsim-generator

What this skill does

# MicroSim Generator

## Overview

This meta-skill routes MicroSim creation requests to the appropriate specialized generator based on visualization requirements. It consolidates 14 individual MicroSim generator skills into a single entry point with on-demand loading of specific implementation guides.

Six Python batch utilities in `src/microsim-utils/` automate the repetitive parts of MicroSim generation (parsing specs, scaffolding files, inserting iframes, fixing iframe heights, validating quality, updating navigation), saving ~430K tokens per batch run. The agent's creative work is focused on writing the `.js` file.

## Default Sequential Execution

When the microsim generator skill us used on all of the #### Diagram elements
of a chapter, always run the microsim generator tasks sequentially unless
the user specifically uses the phrase "execute in parallel".

## When to Use This Skill

Use this skill when users request:

- Interactive educational visualizations
- Data visualizations (charts, graphs, plots)
- Timelines or chronological displays
- Geographic/map visualizations
- Network diagrams or concept maps
- Flowcharts or workflow diagrams
- Mathematical function plots
- Set diagrams (Venn)
- Priority matrices or bubble charts
- Custom simulations or animations
- Comparison tables with ratings
- Matrix comparisons with expandable cell details
- Batch generation of MicroSims for a chapter

---

## Step 0: Environment Setup

Before any generation work, establish paths and determine scope.

### 0.1 Set Paths

```bash
# Python utilities live in the claude-skills repo
UTILS="$HOME/Documents/ws/claude-skills/src/microsim-utils"

# Detect project root (directory containing mkdocs.yml)
PROJECT=$(python3 -c "
import os, sys
d = os.path.abspath('.')
while d != os.path.dirname(d):
    if os.path.isfile(os.path.join(d, 'mkdocs.yml')): print(d); sys.exit()
    d = os.path.dirname(d)
print('ERROR: mkdocs.yml not found', file=sys.stderr); sys.exit(1)
")
```

If the scripts are not found at `$UTILS`, check for them in the project's own `src/microsim-utils/` directory.

### 0.2 Determine Scope

| User Request | Route |
|-------------|-------|
| "Generate MicroSims for chapter 11" | **Chapter batch** → Step 1 |
| "Create a MicroSim for inscribed angles" | **Single sim** → Step 1B |
| "Build a timeline of Unix history" | **Single sim** → Step 1B |

---

## Step 1: Extract Specs from Chapter (Batch Route)

**MANDATORY for chapter-level generation.** Do NOT manually parse chapter markdown.

```bash
python3 $UTILS/extract-sim-specs.py \
    --project-dir $PROJECT \
    --chapter <chapter-dir-name> \
    --output /tmp/ch-specs.json \
    --status-file /tmp/sim-status.json \
    --verbose
```

**What this does:**

- Parses all `#### Diagram:` and `#### Drawing:` headers from the chapter's `index.md`
- Extracts `<details>` block content, iframe paths, sim IDs, Bloom levels, and library hints
- Produces a JSON array of spec objects (one per sim)
- Generates a `sim-status.json` with lifecycle states: `specified → scaffolded → implemented → validated → deployed`

**Read the output:**

```bash
cat /tmp/ch-specs.json | python3 -m json.tool | head -60
```

Check the status file to see which sims need work:

```bash
python3 -c "
import json
with open('/tmp/sim-status.json') as f:
    for e in json.load(f):
        if e['status'] != 'deployed':
            print(f\"  {e['status']:12s}  {e['sim_id']}\")
"
```

After extracting, proceed to **Step 2**.

---

## Step 1B: Single-Sim Shortcut

For a single MicroSim request (not a full chapter batch):

1. **Write a 1-entry spec JSON** manually:

```bash
cat > /tmp/ch-specs.json << 'EOF'
[{
    "sim_id": "inscribed-angle-theorem",
    "title": "Central vs Inscribed Angles Interactive",
    "summary": "Demonstrates the inscribed angle theorem",
    "heading_type": "Diagram",
    "chapter": "",
    "element_type": "microsim",
    "bloom_level": "Analyze",
    "library": "p5.js",
    "iframe_src": "",
    "iframe_height": "",
    "spec_text": "",
    "status": ""
}]
EOF
```

2. **Run scaffold** for just that sim:

```bash
python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --sim-id inscribed-angle-theorem \
    --project-dir $PROJECT \
    --verbose
```

3. **Jump to Step 3** (Instructional Design Checkpoint), then **Step 4** (Implement .js).

---

## Step 2: Scaffold Sim Directories

**MANDATORY for batch generation.** Do NOT manually create main.html, index.md, or metadata.json.

```bash
python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --project-dir $PROJECT \
    --verbose
```

**What this does:**

- Creates `docs/sims/<sim-id>/` directory for each spec
- Generates `main.html` with correct CDN links, `<main>` tag, and schema meta tag
- Generates `index.md` with frontmatter, iframe embed, fullscreen link, lesson plan skeleton
- Generates `metadata.json` with Dublin Core fields and educational metadata
- **Skips** directories that already exist (unless `--force` is used)

**Using `--force` for partially-built sims:**

When sim directories exist (with main.html + .js) but lack index.md or metadata.json, the scaffold script skips the entire directory by default. Use `--force` to regenerate all scaffold files. This is safe because the creative work lives in the `.js` file, which the scaffold never overwrites.

```bash
python3 $UTILS/generate-sim-scaffold.py \
    --spec-file /tmp/ch-specs.json \
    --project-dir $PROJECT \
    --force \
    --verbose
```

**After scaffolding, the agent ONLY writes .js files from here on.**

---

## Step 3: Instructional Design Checkpoint (MANDATORY)

**Before writing any .js file, you MUST complete this checkpoint.**

### 3.1 Identify Learning Objective Details

Extract from the specification:
- **Bloom Level**: Remember, Understand, Apply, Analyze, Evaluate, or Create
- **Bloom Verb**: The action verb (explain, demonstrate, calculate, etc.)
- **Learning Objective**: The full statement of what learners will be able to do

### 3.2 Match Interaction Pattern to Bloom Level

| Bloom Level | Appropriate Patterns | Inappropriate Patterns |
|-------------|---------------------|------------------------|
| Remember (L1) | Flashcards, matching, labeling | Complex simulations |
| **Understand (L2)** | **Step-through worked examples, concrete data visibility** | **Continuous animation, particle effects** |
| Apply (L3) | Parameter sliders, calculators, practice problems | Passive viewing only |
| Analyze (L4) | Network explorers, comparison tools, pattern finders | Pre-computed results |
| Evaluate (L5) | Sorting/ranking activities, rubric tools | No feedback mechanisms |
| Create (L6) | Builders, editors, canvas tools | Rigid templates |

### 3.3 Answer These Questions

Before proceeding, answer these questions:

1. **What specific data must the learner SEE?**
   - Not "animated particles" but "the tokenized array ['physics', 'ball']"

2. **Does the learner need to PREDICT before observing?**
   - If YES → Use step-through with Next/Previous buttons
   - If YES → Do NOT use continuous animation

3. **What does animation add that static arrows don't?**
   - If you can't answer this clearly → Don't use animation

4. **Is continuous animation appropriate for this Bloom level?**
   - For Understand (L2) with verb "explain" → Almost always NO
   - For Apply (L3) with real-time feedback → Often YES

### 3.4 Modify Specification If Needed

If the specification requests animation/effects for an UNDERSTAND level objective:
- **Flag this as a potential instructional design issue**
- **Recommend step-through pattern instead**
- **Ask user**: "The specification requests animation, but for an 'explain' objective, a step-through approach with concrete data visibility typically supports learning better. Should I proceed with step-through instead?"

### 3.5 Document Your Decision

Add to your response:
```
Instructional Design Check:
- Bloom Level: [level]
- Bloom