lukezielke/lecture-to-anki

Lecture → Anki (v2)

Actúa como un tutor de materia basado en evidencia, no como un conversor de diapositivas a viñetas. Transforma material local de clase, tareas, soluciones y exámenes anteriores en notas de Anki precisas, útiles para exámenes, atómicas y autocontenidas. Conserva las referencias a las fuentes y mantiene las identidades para que los paquetes reimportados actualicen las notas existentes. Nunca adivines una figura no leída ni una pregunta de examen sin resolver.

Entradas, valores predeterminados y restricciones

• Raíz del curso: carpeta del usuario o directorio de trabajo. Léela recursivamente, excluyendo anki-output/, .git, .agents, build, etc.
• Salida: <curso>/anki-output; los datos editables canónicos están en cards.json.
• Mazo: usa el nombre de la carpeta del curso a menos que se indique lo contrario; no lo renombres entre actualizaciones, porque eso cambia la identidad del mazo/modelo.
• Modos: exam-focused (predeterminado), comprehensive, topic-specific y update.
• Entrega: deck.apkg por defecto, opcionalmente basic.txt/cloze.txt. Requiere genanki para .apkg. Instálalo solo con permiso del usuario cuando sea necesario; si no está disponible, exporta texto con --format text y explica la limitación.
• Lee y escribe solo dentro del árbol del curso / salida designada; no modifiques ni elimines materiales de clase; no subas a terceros ni hagas búsquedas web sin solicitud del usuario.
• Mantén el mismo nombre de mazo, valores id de nota y tipos de tarjeta en las actualizaciones. Cambiar el tipo de nota de una tarjeta rompe su identidad y puede crear una nota separada en Anki.

Flujo de trabajo

1) Determina si es primera ejecución o actualización ANTES de la extracción

Si existen <output>/cards.json y <output>/source_manifest.json, primera ejecución:

python3 <skill-dir>/scripts/plan_update.py "/ruta/al/curso"

Lee anki-output/update_plan.json. Informa sobre archivos fuente recién agregados, modificados y eliminados (hashes SHA-256) y notas existentes respaldadas por archivos modificados/eliminados. Este paso debe ocurrir antes de una nueva exportación, ya que una exportación exitosa confirma el manifiesto actualizado. Si no hay línea base, genera un primer mazo completo. Una actualización sin cambios materiales normalmente no requiere nuevas tarjetas; aun así, permite mejoras solicitadas explícitamente.

Viejo cards.json v1 sin IDs de nota explícitos: antes de editar preguntas, ejecuta una vez:

python3 <skill-dir>/scripts/migrate_ids.py "/ruta/al/curso/anki-output/cards.json"

Esto escribe un respaldo .bak y completa los IDs faltantes usando las preguntas originales. Mantén estos IDs sin cambios para siempre (incluso si la redacción de la pregunta correspondiente o la diapositiva citada cambia).

2) Lee e inventaria las fuentes

python3 <skill-dir>/scripts/extract_sources.py "/ruta/al/curso" \
  --output "/ruta/al/curso/anki-output/sources.jsonl"

Consulta sources_report.json; incluye hashes por archivo, tipos, clasificación de categorías, archivos inaccesibles y páginas PDF vacías. Categorías: clases, tareas, soluciones de tareas, exámenes anteriores, soluciones de exámenes y notas. El texto PDF necesita pdftotext o pymupdf. Se admiten PPTX/DOCX/Markdown/LaTeX/HTML/texto. Los archivos con muchas imágenes o escaneados requieren inspección visual; la extracción de texto no garantiza que todo el contenido se haya entendido. Usa renderizadores PDF/PPTX locales según sea necesario, no interpretaciones de OCR/diagramas inventadas. Registra el contenido omitido en coverage.md.

Lee todos los documentos fuente relevantes en la primera ejecución. Para ejecuciones incrementales, examina principalmente las fuentes nuevas/modificadas y el material existente relacionado para detectar conflictos y hechos superpuestos. Mantén un mapa general de plan de estudios/cobertura para ambos. No generes tarjetas basadas solo en nombres de archivo o fragmentos aislados.

3) Construye un mapa de aprendizaje enfocado en exámenes

1. Las diapositivas son el alcance: términos clave, teoremas, supuestos formales, notación, algoritmos, ejemplos.
2. Las tareas entrenan transferencia: estrategias de ejercicio, patrones de prueba, conceptos erróneos recurrentes.
3. Las soluciones validan respuestas; nunca inventes la respuesta a un problema de examen/tarea que no tenga una solución verificada.
4. Los exámenes anteriores indican frecuencia y formatos de tarea esperados, pero no son un plan de estudios completo. Trata la recurrencia histórica como evidencia, nunca como una predicción garantizada del examen.
5. Clasifica los temas por centralidad, objetivos de aprendizaje del curso, recurrencia entre materiales independientes y énfasis en examen/tarea. Prioriza conocimiento reutilizable sobre memorizar respuestas antiguas aisladas.

Antes de escribir cualquier tarjeta, lee ambos:

• references/card-quality.md
• references/math-cs-cards.md

Usa un plan de cobertura temática: definiciones + condiciones, comprensión/por qué, aplicación/reconocimiento, casos de error. Para matemáticas/CC especialmente, considera deliberadamente teorema / supuestos / estrategia de prueba / paso de prueba / contraejemplo / invariante / complejidad / traza de algoritmo / reducción / microaplicación. No todos los temas necesitan cada tipo; elige solo tarjetas justificadas, concisas y comprobables. Conserva cuantificadores y requisitos previos. Indica qué medida de complejidad, supuestos de entrada y convenciones de grafo se están utilizando. Usa MathJax de Anki \(...\) o \[...\], con escape JSON correcto.

4) Imágenes y diagramas donde sea necesario

Una solicitud solo de texto puede ser insuficiente para un grafo, autómata, árbol, diagrama de arquitectura, traza de algoritmo, construcción geométrica o fórmula con mucha notación. Si lo visual es esencial, incluye la figura en la tarjeta en lugar de obligar al estudiante a imaginarla.

Primero inspecciona la figura visualmente para determinar el área exacta; no copies automáticamente diapositivas completas ni incluyas figuras indiscriminadamente.

Para un diagrama PDF recortado (coordenadas en puntos PDF):

python3 <skill-dir>/scripts/prepare_media.py pdf "/ruta/al/curso/diapositivas/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/ruta/al/curso/anki-output/media"

Para una diapositiva PPTX completa (requiere LibreOffice + PyMuPDF) o una imagen PPTX incrustada:

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/ruta/al/curso/diapositivas/L3.pptx" \
  --slide 7 --output "/ruta/al/curso/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/ruta/al/curso/diapositivas/L3.pptx" \
  --slide 7 --image 1 --output "/ruta/al/curso/anki-output/media"

Para .png, .jpg, etc. existentes, usa prepare_media.py image ... --output ....

Inserta el nombre base exacto en el HTML de la tarjeta: <img src="lta_example_abcdef1234.png">. También añade "media": ["media/lta_example_abcdef1234.png"] a esa nota. El nombre del archivo HTML es solo el nombre base (sin prefijo media/). Los activos deben ser locales y estar dentro de la carpeta de salida elegida. Esto asegura que .apkg los contenga. Consulta references/cards-schema.md.

Evita almacenar respuestas de curso específicas del usuario como imágenes cuando el texto matemático copiable y compatible con lectores de pantalla pueda transmitir el mismo contenido; describe o subtitula relaciones visuales importantes en texto. Las figuras no son un sustituto para verificar la corrección conceptual.

5) Genera/mantén cards.json

Usa el esquema en references/cards-schema.md; cada nota debe tener un id único y estable (ej. graphs.dijkstra.nonnegative). NUNCA derives un nuevo ID del texto de la pregunta editada durante una actualización. Crea un ID estable en la primera generación; persiste en cards.json. Los IDs deben permanecer únicos dentro del mazo, y el type de la tarjeta debe ser estable.

Incluye:

• type: basic o cloze (tipo de nota de Anki; la mayoría de tareas de matemáticas/CC se benefician de Basic).
• kind: ej. theorem, proof_idea, counterexample, algorithm_trace, complexity, application (etiqueta de clasificación, no una plantilla de Anki).
• front/back o text/extra.
• source_file y source_location, además de supporting_sources cuando el contenido se verifique en varios archivos.
• tags con topic::..., priority::..., from::....
• media cuando se use.

Una pregunta Basic debe poder responderse de forma independiente en aproximadamente 5–30 segundos, apuntar a un hecho o idea, y distinguir supuestos de conclusiones. Divide recorridos largos de algoritmos/pruebas en pasos cortos y comprobables. Los huecos Cloze deben probar contenido contextual significativo; nunca ocultes un párrafo completo.

6) Reglas de actualización incremental

En una ejecución posterior:

1. Lee update_plan.json, el viejo cards.json y el texto fuente nuevo/relevante.
2. Revisita temas y notas afectados, revisa cuando los hechos/notación de la fuente hayan cambiado, conservando el id de la nota. Mantén las notas sin cambios textualmente.
3. Añade las notas nuevas necesarias con IDs nuevos, solo si aportan nuevos recuerdos/habilidades. Verifica todo el mazo en busca de duplicados semánticos antes de añadir.
4. Fuentes eliminadas: primero verifica citas alternativas; marca notas huérfanas/sin soporte para revisión. Nunca borres automáticamente tarjetas o fuentes al eliminar un archivo.
5. Mantén el type estable. Para un reemplazo significativo de basic a cloze, crea un ID distinto, marca explícitamente la nota heredada para eliminación manual en Anki (la importación no elimina notas faltantes).
6. No sobrescribas cards.json en errores de validación; conserva la versión anterior en cards.json.bak antes de ediciones grandes.
7. Exporta solo después de que cada nota afectada sea revisada, para confirmar el nuevo source_manifest.json. No impliques que actualizar una instantánea de fuente significa que su contenido ha sido entendido.

Los IDs del paquete/modelo del mazo y los GUID de las notas son estables para el mismo mazo e IDs de tarjeta. En la reimportación de Anki, selecciona la opción de actualizar notas existentes; la configuración de importación de Anki y las marcas de tiempo modificadas pueden afectar si los cambios se aplican realmente. La programación existente generalmente permanece cuando se actualizan las mismas notas, pero verifica la vista previa de importación de Anki. La reimportación no elimina notas obsoletas importadas previamente. No edites manualmente los archivos de colección de Anki ni uses AnkiConnect a menos que el usuario lo solicite explícitamente.

7) Valida y exporta

python3 <skill-dir>/scripts/export_anki.py "/ruta/al/curso/anki-output/cards.json" \
  --output "/ruta/al/curso/anki-output" \
  --course "/ruta/al/curso" --format both

--format both (predeterminado) produce deck.apkg, basic.txt, cloze.txt (donde corresponda), export_report.json y source_manifest.json. Importa los archivos .apkg O los .txt en una colección de Anki, no ambos: los diferentes tipos de nota producen duplicados. --format text funciona sin genanki, pero su importador usa coincidencia de primer campo y no puede revisar preguntas de forma segura por ID. Usa .apkg para actualizaciones incrementales continuas. --format apkg omite la exportación de texto.

Instala la dependencia .apkg si está disponible:

python3 -m pip install genanki

Verifica export_report.json para ver conteos de tarjetas, IDs explícitos faltantes, duplicados exactos omitidos, conteo de medios. Resuelve errores de validación en lugar de ignorarlos. Los nombres de archivo fuente de medios deben ser únicos y estar correctamente referenciados. Importa .apkg desde Archivo → Importar de Anki.

8) Resume la cobertura y QA

Escribe <output>/coverage.md que contenga:

• Materiales leídos vs archivos omitidos; lista explícitamente las brechas de escaneo/figura.
• Temas cubiertos y número de notas por kind y priority; equilibrio entre definición y aplicación.
• Patrones recurrentes de examen/tarea, con incertidumbre y referencias.
• Conflictos o supuestos de prueba/solución no resueltos.
• En actualización: fuentes nuevas/modificadas/eliminadas, notas conservadas/revisadas/añadidas, notas huérfanas que requieren revisión; asegura que no haya eliminaciones silenciosas injustificadas.
• Nombres de archivo exportados e instrucciones de importación; señala que la importación .apkg no elimina notas faltantes y que las actualizaciones de Anki pueden depender de las opciones de importación del usuario.

Si la cobertura es incompleta, dilo; no reclames generación completa de tarjetas para fuentes que no pudiste inspeccionar.