adamaiken89/learn-something

Marco de Aprendizaje "Learn Something"

Convierte un tema en un plan de estudios estructurado a través de una sesión interactiva con un LLM. Estudia vía CLI: lee lecciones, explica con tus propias palabras, practica con preguntas de opción múltiple y repite con repetición espaciada.

1. Pedagogía

Tres teorías fusionadas:

Teoría	Rol de la IA	Problema resuelto
Marva Collins	Tutor socrático. Preguntas y respuestas rigurosas, altas expectativas, paciencia infinita	Necesita un gran profesor. La IA nunca se cansa.
Técnica Feynman	Detector de lagunas. El alumno explica de forma sencilla → la IA encuentra los vacíos	Ilusión de comprensión
Dificultades Deseables	Planificador de repaso espaciado. Recuperación FSRS + práctica intercalada	Relectura pasiva

Mapeo fase → teoría

Fase	Teoría	Alumno	IA/CLI
Leer	Marva	Estudia la lección	Escribe contenido claro
Explicar	Feynman	Explica el concepto simplemente	Indaga: "dijiste X, pero Y — reconcilia"
Practicar	Marva + Deseable	Responde MCQs, justifica	Califica, explica distractores
Juzgar	Marva	Critica, forma una opinión	Seguimiento socrático
Repasar	Deseable	Recuerdo activo vía FSRS	Programa intervalos óptimos

Presupuesto de tiempo

• Tema: 40 h máx (13 sem × 3 h/sem)
• Módulo: 1.5-3 h, ~15-20 por tema
• Revisión SRS: ~10-15 min diarios

2. Estructura del Contenido

<tema>/
├── syllabus.yaml             # Especificación del curso
├── modules/
│   ├── NN-nombre/
│   │   ├── lesson.md         # Contenido principal + ejercicios
│   │   ├── quiz.yaml         # 8-10 MCQs
│   │   └── cloze.yaml        # 8-10 preguntas de completar
│   └── ...
└── srs/
    ├── deck.json             # Tarjetas FSRS-5
    └── stats.json            # Historial

Plantillas completas en templates/. Clave: syllabus.yaml (esqueleto de 20 módulos), module.md (estructura de la lección), quiz.yaml (formato MCQ de 4 opciones).

3. Protocolo de Creación de Contenido

Flujo de trabajo

1. Alcance (5 min): Pregunta dominio/nivel/presupuesto de tiempo/idioma/caso de uso. Propone un plan de estudios.
2. Etapa de esquema: Verifica el DAG de módulos + la cadena de prerrequisitos. Revisa el presupuesto de tiempo.
3. Por módulo (10 min): Crea el módulo con learn.sh create-module <tema> NN-nombre. Número de dos dígitos con relleno de ceros + nombre en kebab-case (p. ej., 01-intro, 02-conceptos-clave). Escribe lesson.md + quiz.yaml. Aplica las 16 reglas de calidad en línea. Mantén lesson.md con ≤12 000 caracteres. Si el contenido se desborda, divide en módulos adicionales y actualiza el syllabus. El usuario revisa. Procede. 3.5. Validar sintaxis: Ejecuta learn.sh validate-content <tema> [módulo]. Corrige todos los errores de markdown + mermaid antes de continuar.
4. Pre-publicación: Carga content-verify.md. Ejecuta la lista de verificación. Corrige las infracciones.
5. Compilar SRS (2 min): Extrae MCQs → mazo FSRS-5.
6. Cuestionarios acumulativos: Después de cada 3-5 módulos, genera cumulative_quiz.yaml en la raíz del tema. 8-10 preguntas que combinan cloze, MCQ, V/F. Cada una etiquetada con source_modules. Respuestas distribuidas entre A-D.

Principios de contenido

• Alineación CILO: Cada módulo sirve ≥1 objetivo de aprendizaje. Sin relleno.
• Idioma: Todo el contenido en el idioma del syllabus.yaml (es/en/zh/yue).
• Práctico primero: Comienza con un ejemplo concreto antes de la definición abstracta.
• Relevante para el dominio: Escenarios de la industria del alumno.
• Eliminaciones cloze: Cada módulo recibe 3-5 espacios en blanco cloze ({término}). El alumno completa antes de continuar. Obliga a la recuperación durante la lectura.
• Predecir lo siguiente: Cada cadena causal recibe 2-3 bloques de predicción. El alumno se compromete con el resultado antes de la revelación.
• Detección de errores: Cada módulo recibe 1-2 ejercicios de "Encuentra el Error". El aprendizaje basado en errores desarrolla la habilidad diagnóstica.
• Codificación dual: Cada concepto recibe un diagrama (Mermaid, ascii o jerarquía estructurada).
• Diversidad de MCQ: 40% recuerdo, 40% aplicación, 20% de varios pasos.
• Indicación Feynman: Cada lección termina con una tarea de explicación + una sonda de lagunas de la IA.
• Dificultad deseable: El mismo concepto se prueba desde diferentes ángulos en todos los módulos.
• Presupuesto de tiempo: Módulo ≤3 h. Tema ≤40 h.
• Límite de tamaño del módulo: Cada módulo lesson.md ≤12 000 caracteres. ¿Excede el límite? Divide el tema en más módulos. Ajusta el recuento de módulos del syllabus en consecuencia.
• Progresión: Construye sobre prerrequisitos. Los módulos anteriores son fundamentales.
• Omitir permitido: ¿El alumno da información escasa? Genera el contenido de todos modos con valores predeterminados sensatos. No te bloquees.
• Socrático en todo momento: Cada concepto importante va seguido de una pregunta que hace que el alumno se detenga y piense, no solo al final del módulo, sino en línea después de cada nueva idea. Pregunta → respuesta/explicación breve inmediatamente después para que el alumno pueda autocorregirse. Patrón: expón el concepto → pregunta "¿por qué?" o "¿y si...?" → responde.
• Diagramas Mermaid: Para conceptos con lógica de ramificación, máquinas de estado, flujos de trabajo o cadenas causales: genera un diagrama de flujo/secuencia/estado de Mermaid. El tema inyecta automáticamente neutral para compatibilidad con modo oscuro/claro. Utiliza una paleta de tonos tierra apagados para los rellenos de style, visible tanto en temas oscuros como claros. Paleta: azul #5c7a99, verde #5c8a6a, naranja #b8924a, rojo #b86a4a, púrpura #7a5a8a, gris #888. Trazos: usa un tono más oscuro del relleno o #333. Ejemplo: style A fill:#5c7a99,stroke:#333. Colócalo después de la explicación del concepto, antes de la pregunta Piensa.
• Mapa mental del módulo: Cada módulo recibe un mapa mental Mermaid en la parte superior de lesson.md (después de los metadatos, antes de los Objetivos de Aprendizaje). Muestra la jerarquía del conocimiento: concepto central → temas clave → subconceptos. Usa la sintaxis mindmap. Máximo 3 niveles de profundidad.
• Distribución de respuestas: Las claves de respuesta de MCQ deben distribuirse entre A/B/C/D. No más de 2 preguntas consecutivas comparten la misma letra de respuesta. La plantilla muestra B como ejemplo: rota durante la generación.
• Cuestionarios acumulativos: Después de cada 3-5 módulos, genera cumulative_quiz.yaml en la raíz del tema. 8-10 preguntas que combinan cloze, MCQ, V/F. Cada pregunta etiquetada con source_modules. Respuestas distribuidas entre A-D.

Reglas de calidad de contenido (16)

#	Regla	Qué hacer	Ejemplo malo → Ejemplo bueno
1	Explica convenciones	Indica por qué existe la convención, no solo qué es	"Precio cotizado 95" → "95 = 95% de $1,000 nominal. La convención % permite la comparación entre bonos con diferentes valores nominales."
2	Responde preguntas implícitas	Anticipa 1-3 preguntas que el alumno no ha hecho	Silencio sobre cupones → "¿Cambia el cupón alguna vez? No para tasa fija. Sí para FRN (se reinicia periódicamente)."
3	Intuición de convergencia al valor nominal	Explica que el precio → valor nominal al vencimiento es mecánico	"El precio converge al nominal porque el tiempo se reduce + el VP de los FC restantes converge al principal. No impulsado por las tasas."
4	Cadena causal primero	Lógica intuitiva antes que la fórmula	Saltar a la fórmula de fijación de precios de bonos → "Los nuevos bonos pagan 6%. Mi bono paga 4%. El mío menos valioso → el precio baja hasta que el rendimiento coincida."
5	Contexto práctico	Cada número recibe un significado real	"Duración 7.5" → "Un aumento de tasa del 1% → ~7.5% de caída de precio (solo movimientos pequeños; ajuste de convexidad para grandes)."
6	"Qué tan probable"	Indica frecuencias normales frente a raras	Omitir → "La curva de rendimiento se invierte raramente. Cada inversión precedió a una recesión (~8 meses). No perfectamente predictivo."
7	Conceptos erróneos comunes	Señala 1-2 errores específicos que tienen los principiantes	"Cupón más alto = mejor bono" → "No. Los bonos con descuento tienen una ganancia de precio incorporada al vencimiento (acreción)."
8	Socrático en todo momento	Cada sección de concepto integra una pregunta Piensa + respuesta inmediata	El alumno lee pasivamente → se ve obligado a detenerse, procesar
9	Diagramas obligatorios	Cada nuevo concepto obtiene un diagrama. Diagramas Mermaid para lógica de ramificación/estado/flujo; ascii/jerarquía para taxonomías	Sin diagrama → Mermaid mindmap o diagrama de flujo ascii
10	Un ejemplo por concepto	Cada concepto abstracto se vincula a un ejemplo concreto del dominio del alumno (o predeterminado sensato)	Definición abstracta de "derivado" → "Un swap de tipos de interés es como dos partes intercambiándose pagos de intereses fijos por flotantes."
11	Frecuencia de casos extremos	Para cada afirmación, di si la regla general tiene excepciones + con qué frecuencia ocurren.	"La duración mide el riesgo de tasa de interés" → "Sí, para pequeños movimientos. Para grandes, la convexidad importa. Raro pero crítico para bonos de largo plazo."
12	Preguntas de opción múltiple bien elaboradas	Distractores creíbles, que reflejen errores comunes. Sin opciones "todas las anteriores"/"ninguna de las anteriores". El orden de las opciones se aleatoriza.	"¿Qué es un bono? A) Acción B) Bono C) Derivado D) Todas las anteriores" → Distractor creíble: un derivado de renta fija
13	Salida por lotes	No generes lecciones de una en una. Genera el plan de estudios completo primero, luego los módulos en lotes de 3-5 para permitir la revisión.	Generar lecciones una por una → "Genera el syllabus.yaml primero. Luego módulos 01-03, 04-06, etc."
14	Sin aprobación del usuario	El agente debe generar el contenido y luego pedir comentarios, no preguntar primero.	"¿Debería empezar con acciones?" → Genera el módulo 01 de acciones, luego pide comentarios.
15	Menú integrado	Al final de cada lección, ofrece 3 opciones: "1) Siguiente lección", "2) Pregunta de seguimiento", "3) Explicar con tus palabras". El alumno elige números.	Sin opciones → "Lección completa. Opciones: 1) Siguiente 2) Pregunta 3) Explica"
16	Probar en la terminal	Cada comando, fragmento de código, herramienta CLI o secuencia de comandos debe ser probado realmente en la terminal antes de incluirlo.	Fragmento de Python no comprobado → Comando verificado: python3 -c "import math; print(math.sqrt(16))" devuelve 4.0

4. Protocolo de Sesión Interactiva

Roles

• Usuario = Alumno (quiere aprender un tema mediante un diálogo guiado)
• IA = Tutor (sigue el protocolo, genera contenido sobre la marcha)
• CLI = Entorno de estudio (soporte learn.sh para comandos de estudio y autoría)

Flujo de la sesión

1. Inicio: El usuario dice "Aprende [tema]" → La IA ejecuta la etapa de Alcance, propone el plan de estudios.
2. Bucle principal: La IA genera el módulo, el alumno lo estudia vía CLI, luego vuelve al chat para la fase Explicar/Juzgar. Repetir.
3. Final: Después de que todos los módulos estén hechos + repaso SRS activo, la IA emite un resumen de competencias + próximos pasos.

Comandos CLI

Comando	Propósito
learn.sh init <tema>	Inicializa la estructura del tema
learn.sh create-module <tema> NN-nombre	Crea un módulo con plantillas
learn.sh validate-content <tema> [módulo]	Valida markdown + mermaid + quiz
learn.sh study <tema> [módulo]	Inicia el modo de estudio CLI
learn.sh srs-review <tema>	Inicia la sesión de repaso SRS
learn.sh cumulative-quiz <tema>	Genera/ejecuta el cuestionario acumulativo
learn.sh stats <tema>	Muestra el progreso y las estadísticas de SRS

5. Cómo empezar

1. Clona este repositorio.
2. Asegúrate de que learn.sh sea ejecutable (chmod +x learn.sh).
3. Ejecuta learn.sh init <nombre-del-tema> para comenzar.
4. Sigue las indicaciones de la IA para definir el alcance y construir el plan de estudios.

6. Licencia

MIT