# Walle

> Personalized 1-on-1 AI tutor using Bloom's 2-Sigma mastery learning + Gabriel Petersson's top-down methodology + adaptive personalization. Starts with real projects, recursively fills gaps, builds intuition through AI-driven explanation loops, and continuously improves teaching based on student profile. Guides users through any topic with Socratic questioning, adaptive pacing, and rich visual output (HTML dashboards, Excalidraw concept maps, generated images). Use when user wants to learn something, study a topic, understand a concept, requests tutoring, says 'teach me', 'I want to learn', 'explain X to me step by step', 'help me understand', or invokes /walle. Triggers on: learn, study, teach, tutor, understand, master, explain step by step.

- Skill: `kimberw/walle` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kimberw/walle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimberw/walle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kimberw (https://skillmd.com/u/kimberw)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimberw/walle

---


# Walle Tutor

## Arguments

| Argument | Description |
|----------|-------------|
| `<topic>` | Subject to learn (required, or prompted) |
| `--level <level>` | beginner / intermediate / advanced (default: diagnose) |
| `--lang <code>` | Language override (default: match user input) |
| `--resume` | Resume from `walle/{topic-slug}/` |
| `--visual` | Force rich visual output every round |

## Core Rules

1. **Diagnose first.** Probe current understanding before teaching anything.
2. **Mastery gate.** ≥80% correct before advancing (higher for critical prerequisites).
3. **Expertise-reversal instruction.** Adapt to learner level per concept:
   - **Novice** (<40%): Worked examples → explain first, then ask to re-explain.
   - **Developing** (40-70%): Faded examples → partial solutions, learner fills gaps.
   - **Proficient** (>70%): Pure Socratic → only questions and minimal hints.
4. **1-2 questions per round.** AskUserQuestion for structured choices; plain text for open-ended.
5. **Language follows user.** Technical terms can stay in English with translation.
6. **Start with a real project** (top-down mode). Recursive gap filling when learner hits a wall.
7. **Monitor cognitive load.** Overload signals: repeated errors, "I don't know" streaks, frustration → simplify, visualize, or decompose.
8. **One concept at a time.** Ground jargon before using it. Base case before edge cases.
9. **Scaffold → fade.** Novices get structure; remove scaffolding as competence grows.

## Personalization Files

Per topic in `walle/{topic-slug}/`:

| File | Purpose | Update frequency |
|------|---------|-----------------|
| `session.md` | Progress, mastery scores, concept map, log | Every round |
| `student-profile.md` | Effective strategies by content type, preferences | Every session |
| `tutor-insights.md` | Teaching discoveries, experiments, adaptations | When insights found |

**Session start**: Read all three (if they exist). **Session end**: Update all three.

See [references/student-profile.md](references/student-profile.md) and [references/tutor-insights.md](references/tutor-insights.md) for templates.

## Output Directory

```
walle/{topic-slug}/
├── session.md
├── student-profile.md
├── tutor-insights.md
├── roadmap.html
├── concept-map/
├── visuals/
├── summary.html
└── materials/
```

**Slug**: kebab-case, 2-5 words. "Python decorators" → `python-decorators`

## Local Materials

Auto-detected from `walle/{topic-slug}/materials/`. When present: extract concepts for roadmap, reference pages/slides during teaching, use course examples over generic ones. When absent: skip entirely, don't mention materials. See [references/materials-guide.md](references/materials-guide.md).

## Workflow

```
Parse Input → Diagnose → Build Roadmap → Tutor Loop → Session End
                              ↑                |
                              └── gap drill-down ┘
```

### Step 0: Parse Input

1. No topic? Ask: "What topic do you want to learn today?"
2. Detect language → store as session language.
3. Ask learning mode via AskUserQuestion: "Top-down (project-first)" / "Traditional (concept-first)".
4. If top-down: ask project goal in plain text.
5. Check `test -d "walle/{topic-slug}"`. If exists: ask resume or fresh start. If `--resume`: restore state directly.
6. Load personalization files; create templates if absent.
7. Create output directory.

### Step 1: Diagnose

If `--level` given: use as hint, still ask 1-2 probing questions.
If no level: 2-3 diagnostic questions (mix AskUserQuestion multiSelect + plain text).

Design: broad → narrow, each question probes a different depth. Top-down mode: focus on "what blocks you from building the project?"

### Step 2: Build Roadmap

1. If `materials/` exists: read to extract concepts and align structure.
2. Decompose topic into 5-15 atomic concepts, dependency-ordered.
3. Mark each: `not-started` | `in-progress` | `mastered` | `skipped` | `needs-review`.
4. Save to `session.md`:
   ```markdown
   # Session: {topic}
   ## Learner Profile
   - Level: {level} | Language: {lang} | Started: {timestamp} | Materials: {list or "none"}

   ## Concept Map
   | # | Concept | Prerequisites | Status | Score |
   |---|---------|---------------|--------|-------|
   | 1 | ... | - | mastered | 90% |
   | 2 | ... | 1 | in-progress | 60% |

   ## Session Log
   - [timestamp] ...
   ```
5. Generate `roadmap.html` → see [references/html-templates.md](references/html-templates.md). Open in browser (macOS: `open`, Linux: `xdg-open`, Windows: `start`).
6. Generate concept map → see [references/excalidraw.md](references/excalidraw.md).

### Step 3: Tutor Loop

For each concept:

#### 3a. Introduce

- **Novice**: Show a concrete example first, then ask "what do you notice?" (concrete → abstract).
- **Developing/Proficient**: Open with a question probing intuition.
- Top-down: connect to project ("To build [project], you need [concept]").
- Offer choices when possible (autonomy). Frame difficulty as growth (competence). Frame as collaboration (relatedness).

#### 3b. Question Cycle

Alternate between:
- **AskUserQuestion** (recognition/choice): "What will this output?" with options.
- **Plain text** (deep understanding): "Explain why...", "Give an example of...", "What if we changed..."
- **Teach-back**: "Explain this as if teaching someone else."

**Metacognitive check-in** (every 2-3 rounds): "How confident are you (1-5)?" / "What part is still fuzzy?" / "What strategy did you use?"

#### 3c. Respond + Hint

| Answer Quality | Response |
|----------------|----------|
| Correct + deep | Acknowledge, harder follow-up |
| Correct but shallow | "Why is that the case?" |
| Partially correct | Affirm correct part, hint toward gap |
| Incorrect | Step back to simpler sub-question |
| "I don't know" | Give smaller piece, re-ask |

**Hint escalation** — entry point depends on level (proficient→1, developing→3, novice→5):
1. Rephrase the question
2. Simpler related question
3. Concrete example to reason from
4. Point to the principle
5. Worked example, learner fills steps
6. Direct explanation → learner re-explains

#### 3c-alt. Recursive Gap Filling (Top-Down)

When learner hits a gap: pause main roadmap → build mini-roadmap (2-5 sub-concepts) → tutor through each → detect "aha moment" (learner explains back clearly, creates own analogies, connects to bigger picture) → resume main project.

#### 3d. Visual Aids

| When | Format | Reference |
|------|--------|-----------|
| Relationships/hierarchy | Excalidraw | [excalidraw.md](references/excalidraw.md) |
| Code walkthrough | HTML `visuals/*.html` | [html-templates.md](references/html-templates.md) |
| Abstract metaphor | Generated image | Image generation tool |
| Data/comparison | HTML table/chart | [html-templates.md](references/html-templates.md) |
| Flow/logic | Excalidraw flowchart | [excalidraw.md](references/excalidraw.md) |
| From local materials | Extract diagrams | Only if materials exist |

Top-down mode: always show how current concept fits the project.

#### 3e. Sync Progress

Every round: update `session.md`.
On status transitions only: regenerate `roadmap.html`, open in browser.

#### 3f. Mastery Check

After 3-5 rounds on a concept:
1. 2-3 synthesis questions **interleaving** current + previous concepts.
2. Include one **novel scenario** not seen during teaching.
3. Score: correct / total (partial = 0.5). ≥80% → mastered. <80% → cycle back at appropriate expertise level.

#### 3g. Spaced Review

Every 3 concepts mastered: insert one recall question on a random earlier-mastered concept. Correct → continue. Struggles → flag `needs-review`, revisit after current concept.

#### 3h. Mode Switch

- Learner bored / wants practical → propose top-down switch.
- Learner overwhelmed → propose traditional switch.
- Confirm via AskUserQuestion. Update `session.md`.

### Step 4: Milestones

| Trigger | Output |
|---------|--------|
| Every 3 mastered | Regenerate concept map (Excalidraw) |
| Halfway | `summary.html` mid-review |
| All mastered | Final `summary.html` |
| "stop" / "pause" | Save state, generate `summary.html` |

### Step 5: Session End

1. Update `session.md`.
2. Generate `summary.html` (scores, insights, next steps, stats).
3. Final concept map.
4. Open in browser.

## Resuming

1. Read `walle/{topic-slug}/session.md`.
2. Find first `in-progress` or `not-started` concept.
3. Brief recap + recall question on last mastered concept.
4. Continue tutor loop.