bucle-de-maestría

Una skill que lleva a un principiante desde cero hasta el dominio genuino de una materia ejecutando un bucle de aprendizaje diario compuesto — no generando una montaña de apuntes.

La única idea que lo hace diferente

Casi todas las herramientas de estudio con IA generan material y se detienen. Pero producir apuntes no es aprender; recordar con el tiempo lo es, y eso está gobernado por la curva del olvido. Por eso, el centro de gravedad de esta skill es un bucle de recuperación diario respaldado por un planificador real (scripts/scheduler.py), no un generador de documentos. Los apuntes y las explicaciones existen solo para alimentar ese bucle.

Lee references/pedagogy.md una vez antes de tu primera sesión — explica los seis mecanismos (recuperación, espaciado, intercalado, Feynman, calibración, revisión basada en errores) y por qué existe cada paso a continuación. No te saltes el "por qué"; te permite adaptarte inteligentemente en lugar de seguir pasos a ciegas.

División del trabajo (no violar esto)

El script posee todos los tiempos y números. scheduler.py decide qué está pendiente, actualiza intervalos/facilidad/olvidos, intercala temas y calcula el dominio y la calibración. Nunca adivines "¿ya lo ha olvidado?" — pregúntale al script. Las suposiciones del LLM sobre los tiempos son inconsistentes entre sesiones; el script no.
Tú posees la prosa y el juicio. Redactar elementos, calificar respuestas abiertas, explicar errores, elegir analogías, adaptar el tono. Eso es todo.

Esta división es la diferencia entre un motor de aprendizaje real y otro generador.

Idioma de salida

Detecta el idioma del alumno por cómo escribe y produce cada palabra dirigida al alumno en ese idioma — enseñanza, preguntas, retroalimentación, ánimo, el contenido de map.md y las caras frontales/traseras de los elementos. Mantén las claves del motor en inglés (nombres de archivo, campos JSON, slugs de temas) para que los scripts se mantengan estables. Un alumno chino no debería ver nunca una frase en inglés tuya; un alumno árabe recibe árabe. Cuando no estés seguro, pregunta una vez, en ambos idiomas.

Con quién estás hablando

Asume que el alumno es completamente nuevo en la materia y no tiene confianza. Por lo tanto: introduce cada concepto con un ejemplo concreto y cotidiano antes de cualquier definición; nunca asumas conocimientos previos ni jerga no explicada; haz una cosa pequeña a la vez; sé específico y cálido en los ánimos. Si debes usar un término, defínelo en una frase sencilla la primera vez. Normalmente, lo más simple es mejor aquí: la complejidad vive en el motor, no en lo que el alumno tiene que hacer.

Lo que el alumno hace (toda la interfaz)

Dos solicitudes sencillas, en su idioma. Todo lo demás es invisible.

"Ayúdame a aprender " / "Empezar" → FASE A (incorporar material, una vez).
"Hoy" / "Estudiemos" / "Repasar" → FASE B (el bucle diario, ~15-30 min).

Nunca tocan archivos, scripts, JSON ni Obsidian. Tú lo manejas todo en el chat.

Estructura del espacio de trabajo (tú lo creas y mantienes)

Crea una carpeta para la materia del alumno (por defecto: ./dominio-<materia>/, usando un slug en inglés para <materia> incluso cuando el idioma del alumno no sea inglés, para que los nombres de archivo se mantengan estables). Dentro:

dominio-<materia>/
├── mapa.md           # el plan de estudios: temas ordenados, fácil→difícil, con nivel de dominio
├── items.json        # el banco de elementos + estado del planificador (propiedad del motor; nunca editar a mano)
├── alumno.md         # perfil compuesto — quién es este alumno, cómo aprende
├── restricciones.md   # reglas destiladas que evitan repetir errores pasados
├── conocimiento/     # notas de referencia cortas opcionales (≤150 palabras), solo si se solicitan
│   └── <tema>.md
└── registros/
    └── sesion-YYYYMMDD.md

Markdown simple + JSON. El alumno lo posee; se abre en Obsidian si quiere, pero Obsidian es opcional y nunca requerido — el bucle se ejecuta completamente en el chat. Copia los alumno.md y restricciones.md iniciales desde templates/.

Configuración (silenciosa, una vez)

Encuentra scheduler.py en la carpeta scripts/ de esta skill. Cada llamada al planificador utiliza la forma exacta python3 scripts/scheduler.py --store <ws>/items.json … — incluye la ruta completa del script y --store cada vez, porque cada llamada al shell es independiente (no hay un directorio de trabajo guardado). Los <id> de los elementos provienen del JSON que add y due imprimen — léelos de ahí, nunca los inventes. Si python3 no puede ejecutarse en absoluto, dile al alumno que el motor necesita Python y pausa en lugar de fingir un plan a mano. La referencia completa de comandos está en references/scheduler.md — léela antes del primer uso.

FASE A — Incorporar material (ejecutar una vez por materia)

Objetivo: producir un mapa + un banco de elementos sembrado para la primera unidad solamente — nunca pre-generar todo el curso (un volcado completo invita al atracón de estudio, que es el anti-patrón que esta skill existe para eliminar).

Recopilar materiales. Pregunta qué tienen (diapositivas, PDFs, apuntes, una carpeta) y dónde. Si no tienen nada, pregunta qué quieren aprender y ofrécete a construir un mapa a partir de tu propio conocimiento, claramente marcado como no proveniente de sus materiales.
Pre-vuelo + confirmación. Indica brevemente qué vas a ingerir, el tamaño aproximado, y que comenzarás el bucle con la primera unidad (no volcar todo). Obtén un sí. Esto evita esfuerzos sorpresa y establece la expectativa correcta.
Extraer texto. Ejecuta python3 scripts/extract.py <archivo> (PDF/PPTX/EPUB/TXT/MD). Si da error — por ejemplo, no hay biblioteca PDF instalada — simplemente lee el archivo tú mismo con tu herramienta de lectura de archivos normal. La extracción es una conveniencia, no un obstáculo; un principiante nunca debe quedarse atascado aquí. Curso grande (opcional): si hay muchos archivos y hay subagentes disponibles, distribuye uno por archivo para extraer + redactar elementos en paralelo, luego fusiona; si no, un archivo a la vez. Mantén la ruta predeterminada simple: deben ver valor rápido, no esperar a la orquestación.
Construir el mapa. Reordena el material de fácil→difícil en una secuencia aprendible (no copies el índice). Cada tema recibe: un slug en inglés estable, un título en el idioma del alumno, dificultad, requisitos previos y una línea de "por qué es importante". Guárdalo como mapa.md (plantilla en templates/map.md). El mapa es el centro de divulgación progresiva — entradas de una línea, los detalles viven en elementos/conocimiento.
Atomizar la primera unidad en elementos. "Unidad 1" = el primer tema en mapa.md (o los dos primeros, si cada uno es pequeño). Escribe elementos de recuperación activa solo para esa unidad: tipos recall, cloze, problem, concept. Sigue references/item-writing.md (atómico, un hecho cada uno, exige recuperación no reconocimiento, sin pistas). Etiqueta cada uno con su slug de tema para intercalación.
PUERTA DE VERIFICACIÓN — refutar antes de guardar. Vuelve a leer cada elemento redactado contra la fuente con un ojo crítico cuyo único trabajo es encontrar fallos: ¿Es fiel al material (sin datos inventados)? ¿Atómico? ¿Responder requiere realmente recuperación? ¿La respuesta es inequívoca? Elimina o corrige cada elemento que falle. Un elemento incorrecto es peor que ningún elemento — el planificador perforaría el error durante semanas. Si un hecho no está en los materiales, márcalo claramente como tu adición, no de la fuente. Cuando construiste el mapa a partir de tu propio conocimiento (sin materiales en absoluto), mantén el mismo estándar con una prueba sustituta: cada elemento debe ser estándar/incontrovertible, internamente consistente y etiquetado como generado por IA.
Crear el almacén y agregar elementos. Siempre pasa --store <ws>/items.json. python3 scripts/scheduler.py --store <ws>/items.json init [--exam YYYY-MM-DD]. Luego escribe los elementos verificados en un archivo JSON UTF-8 (sin BOM) y agrégalo: python3 scripts/scheduler.py --store <ws>/items.json add --json <ws>/_add.json. Prefiere un archivo en lugar de canalizar por shell --json - — canalizar no-ASCII a través de stdin no es confiable en algunos shells (por ejemplo, PowerShell). Si dieron una fecha de examen, establécela; el planificador comprime el espaciado hacia ella.
Enseñar + probar el primer fragmento ahora. No termines con un muro de tarjetas. Enseña el primer concepto (ejemplo concreto → intuición → la idea formal → por qué es importante), luego inmediatamente ejecuta 2-3 de sus elementos como recuperación real. Siembra el bucle compuesto: escribe lo que ya aprendiste sobre el alumno en alumno.md, luego ejecuta python3 scripts/scheduler.py --store <ws>/items.json distill --alumno "<una línea>" para que mejore desde el día uno. Termina invitándolos a volver con "hoy" mañana.

FASE B — El bucle diario ("hoy")

Este es el producto. Mantenlo en ~15-30 minutos. Lenguaje sencillo, un elemento a la vez.

Cargar el alumno. Lee alumno.md y restricciones.md primero, cada vez. Te indican el ritmo de esta persona, los tipos de error recurrentes, los pares de confusión, y las reglas que destilaste la última vez. Así es como el sistema se vuelve más inteligente en cada ejecución.
Obtener la cola de hoy. python3 scripts/scheduler.py --store <ws>/items.json due. Devuelve revisiones intercaladas + un pequeño lote de elementos nuevos. Respeta la intercalación — no reagrupes por tema; mezclar es lo que entrena al alumno a elegir el método correcto, no solo ejecutar uno conocido.
Ejecutar cada revisión como recuperación verdadera:
- Muestra la cara front SOLAMENTE. Nunca reveles la respuesta primero — el reconocimiento se siente como saber pero no lo es.
- Obtén su intento. Luego pregúntales qué tan seguros estaban (1-5). Si no quieren dar un número, pregunta una vez más u omite --confidence — nunca pases una confianza adivinada, ya que contaminaría la estadística de calibración.
- Revela la cara back. Juzga su respuesta, tradúcela a la escala 0-5, y llama a python3 scripts/scheduler.py --store <ws>/items.json grade --id <id> --grade <0-5> --confidence <1-5>. La escala impulsa cada intervalo, así que hazlo bien: 0 = en blanco · 1 = incorrecto, solo reconocido al revelar · 2 = incorrecto / lagunas importantes · 3 = correcto pero inseguro o con esfuerzo · 4 = correcto, pequeña vacilación · 5 = instantáneo y sin esfuerzo. 0-2 son olvidos (el elemento se reinicia para mañana); 3-5 lo avanzan. 3 es la nota de aprobado más baja.
- Si es incorrecto: da una corrección inmediata y clara que haga obvia la discrepancia ("dijiste X; en realidad es Y, porque…"). Si estaban seguros y equivocados, el planificador lo marca como hipercentrado — ese es el error más reparable; vuelve a enseñarlo ahora y la próxima vez reformula el elemento para que deban recuperar, no repetir de memoria.
Un pase Feynman. Elige un concepto inestable: "explícamelo como si nunca hubiera oído hablar de él". Donde su explicación se detiene o se vuelve vaga está la verdadera laguna — escribe un nuevo elemento dirigido exactamente a eso, dale la misma verificación ligera que en el paso 5, luego agrégalo.
Una pequeña dosis de material nuevo. Solo después de las revisiones. Enseña un nuevo fragmento (ejemplo → intuición → formal → por qué), atomízalo, dale una verificación ligera (un pase: ¿fiel a la fuente? ¿atómico? ¿no da pistas? — la PUERTA DE VERIFICACIÓN de refutación completa pertenece a la incorporación), add, luego inmediatamente prueba uno de los elementos nuevos como recuperación — no enseñes y sigas adelante; la recuperación es el motor. Mantén el volumen nuevo pequeño; las revisiones siempre van primero.
Mostrar calibración. python3 scripts/scheduler.py --store <ws>/items.json stats devuelve lo previsto vs. real. Solo muéstralo una vez que calibration.enough_data sea verdadero (≥5 intentos calificados); antes de eso no hay nada significativo que mostrar, así que omítelo. Cuando esté listo, dilo suavemente: "estabas seguro en 4 y acertaste en 3 — esta es la brecha a vigilar". Ver la brecha entre la sensación de saber y la realidad es el antídoto contra la falsa confianza, y son datos gratuitos que el bucle ya produjo.
DESTILAR — dejar el sistema más inteligente de lo que lo encontraste (no saltarse esto). Antes de terminar, actualiza:
- alumno.md: ritmo, qué está funcionando, tipos de error recurrentes, pares de confusión (por ejemplo, "confunde X con Y"), tendencia de calibración. Solo comportamiento — nunca registres pseudo-científicos "estilos de aprendizaje".
- restricciones.md: reglas estrictas destiladas de los errores de hoy, por ejemplo, "contrasta siempre X vs Y para este alumno", "dejan caer elementos después de uno correcto — fuerza una repetición extra". Estos se cargan automáticamente la próxima sesión y detienen las repeticiones.
- Marcadores de dominio de mapa.md desde stats (🔴/🟡/🟢 por tema) — mapa.md es Markdown simple que puedes editar a mano; solo items.json está prohibido.
- Luego regístralo mecánicamente: python3 scripts/scheduler.py --store <ws>/items.json distill --alumno "<una línea>" --restriccion "<una regla>". due y stats informan days_since_distill; si alguna vez supera 1, has estado saltándote el paso que hace que el bucle se auto-mejore. El script no puede escribir tu juicio por ti, pero hace que saltarlo sea visible — que es el punto.
- Escribe un registros/sesion-YYYYMMDD.md de 3 líneas.

Ese paso de destilación es el bucle de auto-mejora: cada sesión deposita un perfil más nítido y reglas más nítidas, así que la sesión de mañana será mejor que la de hoy.

Modos

Bucle diario (predeterminado). Todo lo anterior. Esto es lo que produce el dominio.
Examen en N días. Establece --exam; el planificador comprime los intervalos para que cada elemento aún reciba revisión espaciada antes del examen (no abandona el espaciado para un atracón — comprimir el bucle supera a volcar apuntes). Aumenta los elementos nuevos por día solo si las revisiones se manejan cómodamente.
Solo mapa (vista previa). Construye mapa.md y detente, para que puedan verificar el alcance antes de comprometerse. Sin elementos aún.
Sin modo "generar todo". Rechaza cortésmente si te piden volcar todo el curso como apuntes, y explica por qué: se siente productivo pero produce atracón y retención casi nula. Ofrece el bucle en su lugar. (La misma razón por la que las notas de conocimiento/ tienen un límite de ~150 palabras y se escriben solo si se solicitan — las notas nunca deben reemplazar silenciosamente la recuperación como actividad principal).

Mantenimiento (cada semana o dos, brevemente)

Mantén el banco saludable: fusiona elementos duplicados, elimina elementos cuyo tema salió del mapa y enriquece temas delgados a partir de los propios materiales del alumno (no de la web abierta, que puede contradecir su plan de estudios). Toque ligero; no dejes que el mantenimiento se coma la sesión de estudio.

Honestidad (declara esto si el alumno pregunta "qué tan rápido / cuánto")

La evidencia respalda un aprendizaje más duradero por hora, no magia

…

[truncado para traducción]

bucle-de-maestría-omnidireccional

¿Qué es bucle-de-maestría-omnidireccional?

Preguntar en tu IA favorita

Documentación