Walid-Ahmed/flashcard-deck

Mazo de tarjetas de estudio

Convierte un tema en un mazo de tarjetas de preguntas y respuestas que enseñan primero el concepto general, se imprimen limpiamente y pueden convertirse en videos de YouTube. Las tarjetas se escriben en un solo archivo Python (deck.py) con pequeñas ayudas, y los scripts empaquetados renderizan todo a partir de él, de modo que corregir una tarjeta es una edición y una reconstrucción.

El trabajo se realiza en cuatro etapas. Pregunta antes de cada etapa que le cueste tiempo al usuario o publique algo, porque un mazo solo es útil si cubre lo que ellos necesitan, y los videos tardan minutos en codificarse.

1. Entrevista: pregunta qué construir.
2. Plan: propón temas y preguntas de tarjetas; obtén un sí.
3. Tarjetas: escribe deck.py, renderiza, revisa cada tarjeta, corrige lo que no encaje.
4. Extras (solo si se desean): videos, miniaturas, publicación.

1. Entrevista

Empieza preguntando, no construyendo. Usa la herramienta AskUserQuestion para que el usuario pueda hacer clic en las respuestas. Pregunta todo en una sola llamada (admite hasta 4 preguntas) y omite cualquier pregunta que el mensaje del usuario o el proyecto abierto ya responda. Ofrece una opción recomendada primero, marcada como "(Recomendado)".

Pregunta sobre lo siguiente. La herramienta admite hasta 4 preguntas, así que cuando la fuente sea el material del usuario y se necesite una quinta pregunta, haz la última en una segunda llamada.

• Fuente: qué cubren las tarjetas. Opciones como: material que ya tienen (archivos o una carpeta: PDFs, diapositivas, apuntes en Word o Markdown, un curso, un repositorio o tarjetas existentes), este repositorio, un tema de tu propio conocimiento o notas que pegarán. Si la solicitud ya nombra la fuente, omite esto.
• Qué tan fielmente seguirlo (solo cuando la fuente es su material): solo lo que dice el material (Recomendado), el material más los fundamentos faltantes marcados como añadidos, o el material como punto de partida.
• Audiencia y profundidad: principiante (una idea por tarjeta, palabras sencillas), intermedio (conceptos más un ejemplo corto de código) o avanzado (compensaciones, casos límite).
• Número máximo de tarjetas: hasta 10 (un conjunto rápido), hasta 20 (Recomendado), hasta 40 (un curso completo) o sin límite (tantas como el material necesite). El usuario puede escribir cualquier otro número. Regístralo como deck(..., max_cards=N): la construcción se detiene si el mazo supera ese límite, por lo que dividir tarjetas después no puede romper el límite silenciosamente. Más tarjetas significan más temas, no tarjetas más largas.
• Salidas: solo imágenes y PDFs de tarjetas (Recomendado), más videos, más videos y miniaturas. Los videos vienen después de que las tarjetas sean aprobadas de todas formas.

Luego, si aún se desconoce, pregunta en texto plano (no se necesita herramienta): el título del mazo que se muestra en cada tarjeta (por ejemplo, "FastAPI" o "Kubernetes"), dónde guardar la salida (sugiere una carpeta flashcards/ en el proyecto actual, o una carpeta nueva), y si los ejemplos de código pueden nombrar el proyecto fuente o deben mantenerse genéricos. Para el material propio del usuario, pregunta también si cada tarjeta debe mostrar de dónde proviene (por ejemplo, "Cap. 3, pág. 42").

2. Plan

Lee primero la fuente. Si es material que el usuario ya tiene, lee references/existing-material.md ahora: cubre la lectura de PDFs, diapositivas, archivos Word, carpetas y tarjetas existentes, mapeando todo el material para que nada se omita silenciosamente, manteniéndose fiel a él y señalando cada tarjeta a su página. Para un tema de tu propio conocimiento, decide qué necesita un alumno en el nivel elegido. Luego propón el mazo como una lista corta: temas en orden de aprendizaje, y debajo de cada uno, una línea por tarjeta con su pregunta. Agrupa por concepto (fundamentos de HTTP, validación, autenticación), no por archivo. Apunta a 3 a 9 tarjetas por tema. Un mazo pequeño (menos de aproximadamente 12 tarjetas) está bien como 2 o 3 temas de 2 a 4 tarjetas.

Mantén el plan dentro del número máximo de tarjetas y deja espacio para una o dos divisiones. Si el material necesita más tarjetas de las que permite el máximo, cubre primero las ideas centrales, luego enumera los temas o secciones omitidos y ofrece aumentar el límite.

Muestra el plan y pide un sí, cambios o recortes antes de escribir las tarjetas. Escribir 40 tarjetas sobre los temas equivocados pierde el tiempo, por lo que esta verificación vale la pena.

3. Tarjetas

Escribe deck.py, primero el primer tema

Copia references/deck_template.py junto a donde irá la salida. Escribe las tarjetas del primer tema, renderiza solo ese tema (--topic 1), muestra al usuario dos o tres de ellas y pregunta si el estilo y la profundidad son correctos. Luego escribe el resto. Descubrir en la tarjeta 3 que el usuario quería tarjetas más cortas es barato; descubrirlo en la tarjeta 40 no lo es. Lee references/components.md antes de escribir la primera tarjeta: muestra cada bloque de construcción (oración principal, recuadros, pasos, tablas, ejemplos de código, llamadas, diagramas) con el HTML a usar.

Cómo escribir una buena tarjeta, y por qué:

• Concepto primero. La pregunta y la oración inicial (el lead) expresan la idea general en palabras que aplican en cualquier lugar. El código específico del proyecto va en un recuadro example(...) con el título "Ejemplo: ...", para que el lector aprenda la regla y luego vea un caso. Cuando el proyecto de ejemplo difiere de la práctica común, dilo en el comentario del ejemplo.
• Una idea por tarjeta. Una pregunta que une dos ideas separadas ("¿Qué es X y cómo se despliega?") necesita dos tarjetas. Un contraste ("¿En qué se diferencia X de Y?") o un par que solo tenga sentido juntos es una idea.
• Lead, luego estructura, luego ejemplo. Una respuesta de una o dos oraciones, luego dos o tres recuadros, pasos o una tabla pequeña que lo desglose, luego una llamada opcional y un ejemplo de código. El lector debería obtener la respuesta solo con el lead.
• El pie de página es la línea para recordar, menos de 15 palabras. La etiqueta es una o dos palabras que nombran la idea.
• Redacción llana y exacta. Oraciones cortas. Nombra códigos de estado reales, nombres de funciones y comandos; no los insinúes.
• Diagramas solo donde añadan algo: un flujo, una decisión con caminos de fallo, o las partes de una URL o mensaje. No en tarjetas cuya tabla ya muestre la estructura.
• Referencias cruzadas indican dónde mirar: "La tarjeta 4 en Estructura de la app muestra el lado del servidor".

Renderiza y revisa

python3 <ruta-del-skill>/scripts/build_deck.py deck.py --out DIR_SALIDA             # cada tarjeta, PDFs, README
python3 <ruta-del-skill>/scripts/build_deck.py deck.py --out DIR_SALIDA --topic 1   # un tema, revisión rápida

<ruta-del-skill> es la carpeta donde se encuentra este SKILL.md. Usa python3, o python donde sea Python 3. El script necesita Python con playwright y Pillow (pip install playwright pillow), además de Google Chrome o playwright install chromium. Renderiza cada tarjeta como PNG A4 apaisado de 2400 x 1698 px, verifica que el contenido de cada tarjeta quepa (alto y ancho) y detiene la ejecución nombrando cualquier tarjeta que no quepa. Luego escribe un PDF por tema, print/all-cards.pdf y README.md.

• Contenido repetido: la verificación de ajuste mide el tamaño, no el sentido. Busca un recuadro que repita un paso o el lead, y córtalo.
• Por encima del máximo: la construcción se detiene si el mazo tiene más tarjetas que max_cards. Fusiona o elimina las tarjetas menos importantes, o pide al usuario que aumente el límite. No lo aumentes por tu cuenta.
• Una tarjeta no cabe: acorta el texto, elimina un recuadro o divídela en dos tarjetas (por ejemplo, "9a" y "9b", o dos preguntas). Nunca reduzcas la fuente para que quepa; las tarjetas deben seguir siendo legibles al imprimir.
• Revisa cada tarjeta después de renderizar, abriendo los PNG. La verificación de ajuste detecta desbordamiento, no una tarjeta confusa, un diagrama engañoso o un error tipográfico. Corrige y vuelve a renderizar; --topic N renderiza un tema rápidamente.
• El espacio sobrante es normal. La construcción informa el espacio sobrante en px CSS en la tarjeta de 1200 x 849 (el PNG es el doble). Una tarjeta simple a menudo deja 150 a 350 px vacíos, y eso está bien para leer e imprimir. No rellenes una tarjeta para llenarla. Si una tarjeta deja más de unos 400 px y se siente escasa, puede merecer un diagrama o un ejemplo, o puede fusionarse con una tarjeta vecina.

4. Extras: videos, miniaturas, publicación

Solo cuando el usuario los quiera, y después de que apruebe las tarjetas. Pregunta qué estilo de video y di aproximadamente cuánto tarda la codificación (unos 15 segundos de codificación por tarjeta en un portátil).

python3 <ruta-del-skill>/scripts/build_videos.py deck.py --cards DIR_TARJETAS --out DIR_VIDEO [--mode both|questions|cards]
python3 <ruta-del-skill>/scripts/build_thumbnails.py deck.py --cards DIR_TARJETAS --out DIR_VIDEO/thumbnails [--mode both|questions|cards]

• --mode both (por defecto): cada pregunta con la respuesta oculta y una barra de tiempo (6 s), luego la tarjeta completa (12 s).
• --mode questions: un cuestionario, cada pregunta durante 10 s, sin respuestas.
• --mode cards: una revisión, cada tarjeta completa durante 15 s.
• Cada modo produce un video por tema y uno con todas las tarjetas, nombrados con el modo (-questions, -cards) para que los estilos nunca se sobrescriban. Pasa el mismo --mode a build_thumbnails.py para que sus nombres coincidan.
• Cada video tiene una introducción y pantallas de título del tema, y una descripción .txt cuyos capítulos YouTube convierte en secciones en las que se puede hacer clic. Los capítulos tienen al menos 10 segundos, que es lo que requiere YouTube.
• Los videos necesitan ffmpeg. Mantén DIR_VIDEO fuera de cualquier repositorio git, ya que los videos son grandes.
• Las miniaturas son JPEG de 1280 x 720 nombrados para coincidir con cada video. topic(..., hook="A · B · C") establece la pequeña línea debajo del título de cada tema.
• Después de construir, ofrece títulos y descripciones listos para YouTube: un título de menos de 70 caracteres con el tema y el gancho, una descripción con la línea inicial, una viñeta por tema, cualquier enlace y los capítulos del .txt.

Pregunta antes de enviar, publicar o subir algo; esas acciones llegan a otras personas. Si los ejemplos de código del mazo provienen del curso o repositorio de otra persona, menciónalo antes de hacerlo público y ofrece una línea de crédito (deck(..., credit="...") la pone en el README).

Cambiar un mazo más tarde

Edita deck.py y ejecuta build_deck.py de nuevo; reconstruye cada tarjeta, los PDFs y el README, y elimina las imágenes de las tarjetas eliminadas. Reconstruye los videos solo si el usuario quiere actualizarlos, y --descriptions-only reescribe solo las descripciones de los videos.

Archivos en esta habilidad

• scripts/build_deck.py: tarjetas, verificación de ajuste, PDFs, README.
• scripts/build_videos.py, scripts/build_thumbnails.py: los extras.
• scripts/flashcards/: las ayudas que importa deck.py (__init__.py), el renderizador (engine.py) y la hoja de estilo de las tarjetas (card.css: amigable para impresión, blanco con contornos de colores, A4 apaisado fijo).
• references/components.md: cada bloque de construcción de tarjeta con un ejemplo. Léelo antes de escribir tarjetas.
• references/deck_template.py: un mazo pequeño funcional para copiar.
• references/existing-material.md: construcción de un mazo a partir de las propias notas, PDFs, diapositivas, repositorio o tarjetas del usuario. Léelo cuando esa sea la fuente.