Mini Lessons

Mini-Lessons Creation Skill

This skill guides you through creating world-class interactive mini-lessons for the PAES mathematics curriculum. Each lesson follows a 6-step pedagogical structure designed to maximize learning.

When to Use This Skill

Invoke this skill when:

• User asks to "create a new lesson" or "add a mini-lesson"
• User wants to implement a specific topic from the curriculum
• User needs help with lesson step components
• User asks about lesson structure or patterns

NOMENCLATURA: Niveles de Competencia vs Niveles Escolares

IMPORTANTE: El sistema usa DOS tipos de códigos que se parecen pero significan cosas diferentes:

M1 y M2: Niveles de Competencia PAES

Los códigos M1 y M2 representan los dos niveles de competencia del examen PAES:

Se usan en:

• IDs de lecciones: m1-alg-001-a, m2-geo-001-a
• Campo level en registros: level: 'M1'
• Carpetas de componentes: components/lessons/m1/, components/lessons/m2/
• Unidades temáticas: M1-ALG-001, M2-NUM-003

1M, 2M, 3M, 4M: Niveles Escolares (Grados)

Los códigos 1M, 2M, 3M, 4M representan los años de enseñanza media:

Se usan en:

• Códigos MINEDUC: MA1M-OA-03 (OA de 1° Medio)
• Campo grade en mapeos: grade: '1M'

Relación entre ambos sistemas

Una lección de Competencia M1 puede cubrir contenidos de varios grados escolares:

Lección: m1-alg-001-a (Competencia M1)
├── minEducOA: ['MA1M-OA-03']  → Cubre OA de 1° Medio
└── minEducOA: ['MA2M-OA-01']  → También puede cubrir OA de 2° Medio

Formato de códigos MINEDUC

MA1M-OA-03
│││  │  └── Número de Objetivo de Aprendizaje
│││  └───── OA = Objetivo de Aprendizaje
│└└──────── 1M = 1° Medio (grado escolar)
└────────── MA = Matemáticas

Otros formatos:

• MA2M-OA-XX → 2° Medio
• FG-MATE-3M-OAC-XX → 3° Medio (Formación General)
• FG-MATE-4M-OAC-XX → 4° Medio (Formación General)

STEP 0: IDENTIFY THE SUBJECT

Before anything else, identify which mathematical subject the lesson covers:

┌─────────────────────────────────────────────────────────────┐
│  📐 ÁLGEBRA (Algebra)                                       │
│  Variables, equations, expressions, factoring               │
│  → Read: .claude/skills/mini-lessons/subjects/algebra-patterns.md │
├─────────────────────────────────────────────────────────────┤
│  🔢 NÚMEROS (Numbers)                                       │
│  Fractions, percentages, decimals, operations               │
│  → Read: .claude/skills/mini-lessons/subjects/numbers-patterns.md │
├─────────────────────────────────────────────────────────────┤
│  📏 GEOMETRÍA (Geometry)                                    │
│  Shapes, areas, perimeters, theorems                        │
│  → Read: .claude/skills/mini-lessons/subjects/geometry-patterns.md │
├─────────────────────────────────────────────────────────────┤
│  🎲 PROBABILIDAD (Probability & Statistics)                 │
│  Probability, data, counting, graphs                        │
│  → Read: .claude/skills/mini-lessons/subjects/probability-patterns.md │
└─────────────────────────────────────────────────────────────┘

Each subject has distinct patterns for hooks, explore steps, and explain steps. Read the subject-specific guide BEFORE proceeding to Phase 1.

Subject Selection Guide: → .claude/skills/mini-lessons/subjects/README.md

THREE-STEP WORKFLOW

Creating a mini-lesson requires THREE steps:

┌─────────────────────────────────────────────────────────────┐
│  STEP 0: IDENTIFY SUBJECT                                   │
│  ─────────────────────────────────────────────────────────  │
│  Determine if this is Álgebra, Números, Geometría, or       │
│  Probabilidad. Read the subject-specific pattern guide.     │
│                                                             │
│  Read: .claude/skills/mini-lessons/subjects/README.md       │
│  Read: .claude/skills/mini-lessons/subjects/{subject}-patterns.md │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  PHASE 1: DEEP THINKING (Pedagogical Design)                │
│  ─────────────────────────────────────────────────────────  │
│  Use extended thinking to complete pedagogical design       │
│  BEFORE writing any code. Apply subject-specific patterns.  │
│                                                             │
│  Read: .claude/skills/mini-lessons/pedagogical-design.md    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  PHASE 2: IMPLEMENTATION (Error-Free Execution)             │
│  ─────────────────────────────────────────────────────────  │
│  Follow the 5 Critical Rules and create all files.          │
│  Use subject-specific templates and patterns.               │
│                                                             │
│  Read: .claude/skills/mini-lessons/anti-patterns.md         │
│  Read: .claude/skills/mini-lessons/step-templates.md        │
└─────────────────────────────────────────────────────────────┘

PHASE 1: DEEP THINKING (Summary)

MANDATORY: Before writing ANY code, use extended thinking to complete:

1. Learning Objective Analysis - What concept, prerequisites, misconceptions?
2. ZPD Analysis - Scaffolding strategy from current ability to learning edge
3. Lesson Narrative Arc - Cognitive AND emotional journey for all 6 steps
4. Real-World Hook Design - Culturally relevant, genuinely puzzling scenario
5. Multiple Representations - Visual, symbolic, verbal, kinesthetic, numeric

For detailed frameworks and templates, read: → .claude/skills/mini-lessons/pedagogical-design.md

PHASE 2: IMPLEMENTATION

The 6-Step Structure

Important: Step Types vs File Names

The TypeScript types define 5 step types: 'hook' | 'explore' | 'explain' | 'practice' | 'verify'

Component files are named Step4Classify.tsx but the step type in the lesson registration must use type: 'explore' (since 'classify' is not a valid type). The step id can be 'classify'.

// CORRECT registration - id is 'classify', type is 'explore'
{ id: 'classify', type: 'explore', title: 'Clasifica las Expresiones' }

5-Step Lessons (Variation)

Some lessons skip Step3Explain when theory is integrated into exploration:

components/lessons/m1/{lesson-slug}/
  ├─ Step1Hook.tsx
  ├─ Step2Explore.tsx      # Contains embedded theory
  ├─ Step3Classify.tsx     # Replaces Step4, numbered Step3
  ├─ Step4Practice.tsx     # Replaces Step5, numbered Step4
  ├─ Step5Verify.tsx       # Replaces Step6, numbered Step5
  └─ index.ts

When to use 5-step:

• Geometry lessons where visual exploration IS the explanation
• Simple concepts that don't need separate theory step
• Example: area-paralelogramos-trapecios

Step1Hook: Multi-Phase Pattern (Recommended)

80%+ of lessons use the 4-phase hook pattern. This is the PRIMARY approach:

┌──────────────────────────────────────────────────────────────┐
│ Phase 1: SCENARIO                                            │
│ Present real-world situation with visual (emoji, SVG, image) │
│ "Don Pedro tiene una frutería..."                            │
│ [Explorar →]                                                 │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│ Phase 2: QUESTION                                            │
│ Pose the puzzle with multiple-choice options                 │
│ Show options A, B, C, D                                      │
│ [Verificar]                                                  │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│ Phase 3: REVEAL                                              │
│ Show if correct/incorrect with brief feedback                │
│ "¡Correcto!" or "¡Casi!"                                     │
│ (auto-advance after 1.5s)                                    │
└──────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────┐
│ Phase 4: RESULT                                              │
│ Bridge to the math concept                                   │
│ "Esto es exactamente lo que hacemos con..."                  │
│ [Descubrir el patrón →]                                      │
└──────────────────────────────────────────────────────────────┘

Implementation:

type Phase = 'scenario' | 'question' | 'reveal' | 'result';
const [phase, setPhase] = useState<Phase>('scenario');

Step3Explain: Pattern Decision Tree

Choose the right pattern for your Explain step:

                    ┌─────────────────────────────────────┐
                    │ Does the content have multiple      │
                    │ PARALLEL concepts that can be       │
                    │ explored in any order?              │
                    └───────────────┬─────────────────────┘
                                    │
               ┌────────────────────┴────────────────────┐
               │                                         │
              YES                                       NO
               │                                         │
               ▼                                         ▼
    ┌──────────────────────┐              ┌──────────────────────┐
    │ Use TABBED Interface │              │ Use PHASE-BASED      │
    │                      │              │ Navigation           │
    │ • Factor Numérico    │              │                      │
    │ • Factor Variable    │              │ • Definition → Method│
    │ • Factor Combinado   │              │ • Method → Formula   │
    │ • Tips               │              │ • Formula → Tips     │
    │                      │              │                      │
    │ User can jump to any │              │ Content builds on    │
    │ tab in any order     │              │ previous phase       │
    └──────────────────────┘              └──────────────────────┘

Examples:

• Tabbed: Factor Común (4 types), Productos Notables (4 formulas)
• Phase-based: MCM/MCD (definition → method → formula), Ecuaciones Lineales

Acceptable Variations

While the patterns above are preferred, these variations are also acceptable:

1. Phase-based Step3Explain: For linear content, back/forward navigation is valid

   • See anti-patterns.md → "Valid Alternative Patterns"

2. Custom Step6Verify: When questions need embedded charts/diagrams

   • Must document why CheckpointQuiz isn't sufficient

3. 5-Step Pipeline: Some geometry lessons skip Step3Explain

   • Only for lessons where theory is integrated into exploration

Custom Step File Names

While the standard naming is Step2Explore.tsx, you can use descriptive names to clarify the step's purpose. 43 of 48 lessons use custom names. The step number must match the progression.

Common custom names:

Step2ExploreMultiples.tsx    # Múltiplos lesson
Step2ExploreDice.tsx         # Probabilidad with dice
Step2FractionBars.tsx        # Fracciones visualization
Step3Proof.tsx               # Teorema Pitágoras
Step4Comparison.tsx          # Comparing numbers
Step5ExploreTiles.tsx        # MCD with tile visualization
Step5AbsoluteValue.tsx       # Valor absoluto exploration

Rules for custom names:

1. Keep step number prefix - Step2..., Step3..., etc.
2. Be descriptive - Name describes the activity or content
3. Update index.ts exports - Match the actual file names
4. Match lesson registry - The id in steps array should align

Example index.ts with custom names:

export { default as Step1Hook } from './Step1Hook';
export { default as Step2ExploreMultiples } from './Step2ExploreMultiples';
export { default as Step3Explain } from './Step3Explain';
export { default as Step4Practice } from './Step4Practice';
export { default as Step5ExploreSynchronization } from './Step5ExploreSynchronization';
export { default as Step6Verify } from './Step6Verify';

File Organization

app/lessons/m1/{lesson-slug}/
  └─ page.tsx                    # Main lesson page

components/lessons/m1/{lesson-slug}/
  ├─ Step1Hook.tsx
  ├─ Step2Explore.tsx
  ├─ Step3Explain.tsx
  ├─ Step4Classify.tsx
  ├─ Step5Practice.tsx
  ├─ Step6Verify.tsx
  └─ index.ts                    # Barrel exports

lib/lessons/lessons/{subject}.ts  # Lesson registry

5 CRITICAL IMPLEMENTATION RULES

These rules are NON-NEGOTIABLE. Violating them creates broken lessons.

RULE 1: isActive Check (MANDATORY)

export default function StepN({ onComplete, isActive }: LessonStepProps) {
  const [state, setState] = useState(...);

  if (!isActive) return null;  // THIS LINE IS MANDATORY

  return <div>...</div>;
}

RULE 2: onComplete Call (MANDATORY)

<button

Every step MUST call onComplete when finished.

RULE 3: Tips INSIDE Tabs (Step3Explain)

Tips MUST be inside a dedicated "Tips" tab, NOT as a standalone section.

// 1. Include 'tips' in TabId type
type TabId = 'formula1' | 'formula2' | 'tips';

// 2. Conditional rendering
{activeTab === 'tips' ? (
  <TipsContent />
) : (
  <FormulaContent />
)}

CANONICAL EXAMPLE: components/lessons/m1/factor-comun/Step3Explain.tsx

RULE 4: CheckpointQuiz for Step6 (MANDATORY)

import { CheckpointQuiz, CheckpointQuestion } from '@/components/lessons/shared';

const QUESTIONS: CheckpointQuestion[] = [
  {
    id: 'q1',
    question: '¿Pregunta?',
    options: ['A', 'B', 'C', 'D'],
    correctAnswer: 0,
    explanation: 'Explicación.',
  },
  // 3-4 questions total
];

export default function Step6Verify({ onComplete, isActive }: LessonStepProps) {
  return (
    <CheckpointQuiz
     
      isActive={isActive}
      questions={QUESTIONS}
      requiredCorrect={3}
      successMessage="¡Excelente!"
    />
  );
}

RULE 5: Dark Mode Classes (MANDATORY)

// CORRECT
<div className="bg-blue-50 dark:bg-blue-900/30 text-gray-700 dark:text-gray-300">

// WRONG - missing dark: variants
<div className="bg-blue-50 text-gray-700">

Anti-Pattern Detection

Before completing, verify NO anti-patterns exist.

Read the full anti-pattern guide: → .claude/skills/mini-lessons/anti-patterns.md

Quick Checks:

• Search for "Tips" - must be inside {activeTab === 'tips' ? ...}
• Search for if (!isActive) return null; - must exist in ALL steps
• Step6Verify should be ~30-40 lines (using CheckpointQuiz)
• Search for bg- - must have dark: variant

Step Templates

For complete code templates with placeholders, read: → .claude/skills/mini-lessons/step-templates.md

Lesson Registration

Add to lib/lessons/lessons/{subject}.ts:

{
  id: 'm1-xxx-001-x',
  slug: 'lesson-slug',
  title: 'Título de la Lección',
  description: 'Descripción breve.',
  level: 'M1',
  subject: 'álgebra',  // 'números' | 'álgebra' | 'geometría' | 'probabilidad'
  thematicUnit: 'M1-XXX-001',
  skills: ['skill-1', 'skill-2'],
  estimatedMinutes: 14,
  minEducOA: ['MA1M-OA-03'],  // MINEDUC Learning Objectives
  steps: [
    { id: 'hook', type: 'hook', title: 'Título del Hook' },
    { id: 'explore', type: 'explore', title: 'Descubre el Patrón' },
    { id: 'explain', type: 'explain', title: 'La Teoría' },
    { id: 'classify', type: 'explore', title: 'Clasifica' },  // Note: type is 'explore'
    { id: 'practice', type: 'practice', title: 'Practica' },
    { id: 'verify', type: 'verify', title: 'Checkpoint' },
  ],
},

minEducOA Field

The minEducOA field maps lessons to Chile's official MINEDUC Learning Objectives (Objetivos de Aprendizaje). This enables:

• Curriculum alignment tracking
• Teacher lesson planning
• PAES coverage analysis

Common M1 codes:

For complete OA reference, see: .claude/skills/mini-lessons/reference.md

Page Component Template

'use client';

import { useRouter } from 'next/navigation';
import { LessonShell } from '@/components/lessons/shared';
import { getLessonBySlug } from '@/lib/lessons/types';
import {
  Step1Hook, Step2Explore, Step3Explain,
  Step4Classify, Step5Practice, Step6Verify,
} from '@/components/lessons/m1/{lesson-slug}';

const LESSON_SLUG = '{lesson-slug}';

export default function LessonPage() {
  const router = useRouter();
  const lesson = getLessonBySlug(LESSON_SLUG);

  if (!lesson) {
    return <div className="min-h-screen flex items-center justify-center">
      <p className="text-gray-500">Lección no encontrada</p>
    </div>;
  }

  return (
    <LessonShell
      lesson={lesson}
      => router.push('/mini-lessons')}
      => router.push('/mini-lessons')}
    >
      {({ currentStep, completeStep }) => {
        const steps = [
          <Step1Hook key="1" isActive={currentStep === 0} />,
          <Step2Explore key="2" isActive={currentStep === 1} />,
          <Step3Explain key="3" isActive={currentStep === 2} />,
          <Step4Classify key="4" isActive={currentStep === 3} />,
          <Step5Practice key="5" isActive={currentStep === 4} />,
          <Step6Verify key="6" isActive={currentStep === 5} />,
        ];
        return steps[currentStep] || null;
      }}
    </LessonShell>
  );
}

Index Exports

// components/lessons/m1/{lesson-slug}/index.ts
export { default as Step1Hook } from './Step1Hook';
export { default as Step2Explore } from './Step2Explore';
export { default as Step3Explain } from './Step3Explain';
export { default as Step4Classify } from './Step4Classify';
export { default as Step5Practice } from './Step5Practice';
export { default as Step6Verify } from './Step6Verify';

Quality Gates

All gates must pass before completion.

Gate 1: Pedagogical Quality

• Hook uses real-world scenario (not abstract math)
• Explore has discovery BEFORE explanation
• Explain has Tips INSIDE tabs
• Progressive difficulty curve
• All text in Spanish
• Growth mindset language ("¡Casi!" not "Incorrecto")

Gate 2: Technical Compliance

• All 6 step components created
• index.ts exports all steps
• page.tsx uses LessonShell
• Lesson registered in lib/lessons/lessons/{subject}.ts
• No TypeScript errors
• No lint errors

Gate 3: Implementation Rules

• RULE 1: isActive check in ALL steps
• RULE 2: onComplete called in ALL steps
• RULE 3: Tips inside tabs (Step3)
• RULE 4: CheckpointQuiz used (Step6)
• RULE 5: Dark mode classes on ALL colors

Gate 4: Content Quality

• Checkpoint questions test ALL steps
• Explanations are clear and step-by-step
• Hints are genuinely helpful
• Duration is 12-17 minutes

Quick Reference

For detailed reference materials, read: → .claude/skills/mini-lessons/reference.md

For pedagogical design guidance (Phase 1 planning), read: → .claude/skills/mini-lessons/pedagogical-design.md

Exemplar Lessons (Study These)

• components/lessons/m1/factor-comun/ - Best Tips-in-tabs pattern
• components/lessons/m1/terminos-semejantes/ - Best hook design
• components/lessons/m1/figuras-compuestas/ - Best visual exploration

DO NOT Copy

• components/lessons/m1/productos-notables-cubos/Step3Explain.tsx - Tips outside tabs

Shared Components

Import from @/components/lessons/shared:

• LessonShell - Lesson page wrapper
• CheckpointQuiz - Step 6 verify (ALWAYS use)
• Celebration - Success animations
• NumberLine - Number visualization (Números)
• BarChart, PieChart - Data visualization (Probabilidad)
• FrequencyTable - Frequency tables with tally marks (Probabilidad)
• FactorGrid - Divisor/factor visualization (Números)
• VennDiagram - Set theory diagrams (Probabilidad)

For full component props, see: .claude/skills/mini-lessons/reference.md

Mini-Lesson Toolbox

Composable hooks and primitives to build Step4/Step5 faster while keeping full control.

For full documentation, read: → .claude/skills/mini-lessons/toolbox.md

Quick Reference

Hooks (@/hooks/lessons):

• useMultipleChoice - State for multiple-choice sequences
• useHintToggle - Toggle hint visibility

Primitives (@/components/lessons/primitives):

• ProgressDots - Progress indicator dots
• FeedbackPanel - Correct/incorrect feedback
• OptionButton - Answer option with states
• HintPanel - Collapsible hint
• ActionButton - Primary action button
• ResultsSummary - End-of-step results

Colors (@/lib/lessons/styles):

• colors.feedback, colors.option, colors.progressDot, colors.gradient, colors.hint

Canonical Examples

• components/lessons/m1/completar-cuadrado/Step4Classify.tsx
• components/lessons/m1/completar-cuadrado/Step5Practice.tsx

Final Checklist

• Phase 1 thinking completed
• All 6 step components created
• index.ts exports all steps
• page.tsx with LessonShell
• Lesson registered in types
• All 5 rules verified
• No anti-patterns
• All quality gates passed
• Spanish throughout
• No errors