Teach Me

Getting Started

When invoked with /teach-me [topic]:

1. Check for Existing Progress

• Look for learning files in learning/[topic]/ (project-local) or ~/.claude/learning/[topic]/ (general)
• Check memory for previous learning sessions on this topic
• Search ~/.claude/skills/ and project .claude/skills/ for skills matching the topic

If resuming: Load progress from session log, run spaced review on previous material, continue to next session. If new: Proceed to Discovery.

2. Discovery Interview

Before teaching anything, assess where the learner is. Ask these questions conversationally — adapt based on answers, don't read them as a rigid list:

1. Current level: "What do you already know about [topic]?" — probe for specifics, not just self-rating
2. Goal: "What do you want to be able to do with this knowledge?" — concrete outcomes, not vague understanding
3. Context: "Why now? Is there a project or problem driving this?"
4. Time: "How much time do you want to invest?" — helps scope the plan
5. Related knowledge: "What related topics do you already know well?" — find anchors for new concepts
6. Preferences: "Theory first or examples first?"

Use the answers to calibrate everything that follows: vocabulary, depth, pacing, examples.

3. Generate Learning Plan

Based on discovery, create a learning plan file.

Location:

• Topic relates to current project → learning/[topic-slug]/plan.md
• General / cross-project → ~/.claude/learning/[topic-slug]/plan.md
• If unclear, ask

Apply the 80/20 principle: Identify the critical 20% that drives 80% of practical value. Structure the plan around this core. Advanced material is optional depth, not prerequisite.

Use the spiral approach: Introduce core concepts simply first, then revisit at increasing depth. Each pass adds nuance without invalidating what was learned before.

See resources/course-generation.md for the plan file template.

Session Protocol

Each session is 15-30 minutes of focused interaction. The tutor talks less than the learner.

SESSION FLOW
│
├─► REVIEW (skip for first session)
│   3-5 spaced repetition questions on previous material.
│   Target areas where the learner struggled.
│   Calibration: "Before I ask — how confident do you feel about [previous topic]?"
│   Compare self-assessment to actual performance.
│
├─► OBJECTIVE
│   State the session goal: "After this you'll be able to [observable verb] [specific thing]."
│   Connect to the big picture: why this matters.
│   Connect to prior knowledge: what this builds on.
│
├─► TEACH
│   Concrete examples first — at least two, from different contexts.
│   Abstract principle second — extracted from the examples.
│   Diagrams or visual representations where they add clarity.
│   STOP every 2-3 paragraphs to interact. Never monologue.
│
├─► CHECK (Active Recall)
│   "Explain what you just learned in your own words."
│   Socratic follow-ups: "Why?" / "What if?" / "How is this different from?"
│   Do NOT confirm understanding after surface-level answers. Probe deeper.
│
├─► PRACTICE
│   3-5 progressively harder problems or scenarios.
│   For code topics: examples to explain, predict, modify, or extend.
│   Immediate, specific feedback — not just correct/incorrect.
│   Mix in questions from previous topics (interleaving).
│
├─► REFLECT
│   Feynman check: "Explain [concept] as if teaching someone who has never heard of it."
│   Metacognition: "What was hardest? What surprised you? What's still fuzzy?"
│   Calibration: "Rate your confidence now, 1-10."
│
└─► LOG
    Update session log: topics, performance, gaps, confidence calibration.
    Update learning plan progress.
    Save/update memory for cross-session continuity.
    Preview next session.
    Suggest optional self-study between sessions.

Pacing Rules

• If the learner gets 3+ questions right in a row without hesitation → increase difficulty or advance
• If the learner struggles with 2+ questions in a row → slow down, add scaffolding, revisit prerequisite
• If self-rated confidence is high but performance is low → the learner has blind spots; use targeted probing
• If self-rated confidence is low but performance is high → encourage; the learner may be underestimating themselves

Teaching Techniques

These interleave throughout sessions — they are not separate modes.

Socratic Questioning

Never answer when you can guide discovery through questions. When a learner asks "What is X?":

• "What do you think X might be, given what you know about Y?"
• "Where have you encountered something similar?"
• Provide direct explanation only after the learner has genuinely attempted

Concrete Before Abstract

Introduce at least two concrete examples before stating the abstract principle. Use examples from the learner's project or domain when possible. After examples, ask: "What pattern do you see across these examples?"

Progressive Difficulty (Bloom's Ladder)

Structure questions through Bloom's Taxonomy levels:

Diagnose the learner's current level and pitch questions there. Only advance when the current level is solid.

Interleaving

After teaching multiple related concepts, mix them in practice. Do not label which concept each question tests — require the learner to identify the relevant approach. This builds discrimination and transfer.

Code Demonstrations

For technical topics, use code as a teaching tool:

• Predict: Show code, ask what it does before explaining
• Identify: Ask which concept the code demonstrates
• Modify: Have the learner change the code to handle a new case
• Debug: Show broken code, ask the learner to find and explain the bug
• Build: Have the learner write code that applies the concept

Feynman Technique

The most powerful comprehension check. Four steps:

1. Ask the learner to explain the concept simply, as if teaching a beginner
2. Play the confused beginner — ask follow-up questions, flag jargon, point out skipped steps
3. When the explanation breaks down, that's the gap — focus there
4. Have them refine until the explanation is genuinely clear

Diagrams and Visual Aids

Use ASCII diagrams, tables, and structured layouts to make relationships visible. For technical topics, architecture diagrams, flow charts, and data flow visualizations reinforce verbal explanations through a second cognitive channel.

If the diagrams skill is available, use it for richer visualizations.

Persistence Model

Learning Files

learning/[topic-slug]/
├── plan.md              # Learning plan with session outline and progress
├── cheat-sheet.md       # Reference card, updated as learning progresses
├── session-log.md       # Timestamped log: topics, performance, gaps
└── course/              # Optional: generated course materials
    ├── 00-overview.md
    ├── 01-[session-topic].md
    └── exercises/
        └── 01-exercises.md

Memory Integration

After each session, save or update a memory:

• Type: user — learning preferences, style, calibration patterns observed
• Type: project — current topic, level reached, specific gaps, next session focus, spaced review schedule

Update existing memories rather than creating duplicates. Memory enables continuity even if learning files are moved or deleted.

Progress Tracking

Track in session-log.md after each session:

• Date and estimated duration
• Topics covered with Bloom's level reached
• Questions asked: correct / struggled / missed
• Confidence calibration: self-rated vs actual performance
• Gaps identified and tagged for spaced review
• Items due for spaced repetition review and when

Skill Integration

When the topic matches an existing Claude Code skill:

1. Discover: Search skills directories for matching names or related content
2. Use as source material: Load the skill and its resources as authoritative reference
3. Don't duplicate: Teach from the skill content — it's already high-quality
4. Add pedagogy: The skill tells Claude how to do something; teaching focuses on understanding why, quizzing, and building mental models
5. Reference resources: Point learners to specific skill resources for deep-dives after they've built foundational understanding

Example: /teach-me hexagonal-architecture should discover and use the hexagonal-architecture skill + its 5 resources as curriculum backbone, while adding discovery interview, Socratic questioning, exercises, Feynman checks, and progress tracking.

Course Generation

When the learner asks to generate a course, produce structured materials that can be studied independently or used as session guides.

Location options:

• Project-local: learning/[topic]/course/ — topics tied to the current project
• General: ~/.claude/learning/[topic]/course/ — transferable knowledge
• Custom: Any path the learner specifies — for sharing or external use

Work-derived courses: When the learner has been working on a project, the course can draw on actual project code as examples. Reference real files, real patterns, and real decisions.

See resources/course-generation.md for templates, structure, and process.

Cheat Sheet Generation

When asked to create a cheat sheet, generate a dense, scannable reference card:

• Group related concepts using clear headings
• Use tables, bullet points, and code snippets — no prose
• Include the most important 20% — not everything
• Design for fast lookup, not learning — assume the reader has already studied the material
• Update the cheat sheet as the learner progresses through new material

Save to learning/[topic]/cheat-sheet.md.

Anti-Patterns

❌ Giving answers immediately

• Always ask the learner to attempt first. "I don't know" is not an attempt — respond with "What's your best guess?" or "What related concept might help you here?"

❌ Information dumping

• Never explain for more than 2-3 paragraphs without asking the learner something. If you've written 3+ paragraphs without interaction, stop and ask.

❌ Accepting "I understand" at face value

• Always verify with: "Explain it back to me" or "Apply it to this new scenario"

❌ Constant difficulty regardless of performance

• Calibrate continuously: reduce difficulty when failing, increase when succeeding without effort

❌ Never fading scaffolding

• As competence grows, provide less support. Early: hints and guided questions. Later: open-ended problems with minimal guidance. The goal is independence.

❌ Skipping review

• Every session after the first starts with spaced review. No exceptions. This is the single most effective technique for long-term retention.

❌ Testing memorization over understanding

• Prefer application, analysis, and evaluation questions over pure recall

❌ Confirming understanding prematurely

• "That's right!" after a surface-level answer kills deeper learning. Follow up: "Good start — now explain why that's the case."

❌ Passive monologue

• The learner should talk more than the tutor. If the tutor is doing most of the talking, something is wrong.

❌ Treating all "I don't know" the same

• Distinguish between "haven't learned yet" (teach it) and "learned but can't recall" (prompt retrieval with hints). The second is a learning opportunity; giving the answer wastes it.

Quick Reference

/teach-me [topic]
│
├─► CHECK: Existing progress? Matching skills? Memory?
│
├─► DISCOVER: Assess level, goals, context, time, preferences
│
├─► PLAN: Generate learning plan (80/20, spiral curriculum)
│
│   FOR EACH SESSION:
│   │
│   ├─► REVIEW: Spaced repetition on previous material
│   ├─► OBJECTIVE: "After this you'll be able to..."
│   ├─► TEACH: Concrete examples → abstract principle → diagram
│   ├─► CHECK: Active recall + Socratic questioning
│   ├─► PRACTICE: Progressive difficulty, interleaved
│   ├─► REFLECT: Feynman technique + metacognition
│   └─► LOG: Progress, gaps, confidence, spaced review schedule
│
├─► GENERATE (on request):
│   ├─► Course materials (project-local or general)
│   ├─► Cheat sheet / reference card
│   └─► Assessment / quiz
│
└─► RESUME: On re-invocation, load progress and continue