Walid-Ahmed/flashcard-deck

Jeu de fiches (Flashcard deck)

Transformez un sujet en un jeu de fiches question-réponse qui enseignent d'abord le concept général, s'impriment proprement et peuvent devenir des vidéos YouTube. Les fiches sont écrites dans un seul fichier Python (deck.py) avec de petits assistants, et des scripts groupés génèrent tout à partir de celui-ci, de sorte qu'une correction sur une fiche correspond à une édition et une reconstruction.

Le travail se déroule en quatre étapes. Demandez avant chaque étape qui coûte du temps à l'utilisateur ou publie quoi que ce soit, car un jeu de fiches n'est utile que s'il couvre ce dont l'utilisateur a besoin, et les vidéos prennent plusieurs minutes à encoder.

1. Entretien : demandez ce qu'il faut construire.
2. Planification : proposez des thèmes et des questions de fiches ; obtenez un accord.
3. Fiches : écrivez deck.py, générez le rendu, examinez chaque fiche, corrigez ce qui ne convient pas.
4. Extras (uniquement si souhaité) : vidéos, vignettes, publication.

1. Entretien

Commencez par demander, pas par construire. Utilisez l'outil AskUserQuestion pour que l'utilisateur puisse cliquer sur les réponses. Posez toutes les questions en un seul appel (il peut en contenir jusqu'à 4), et sautez toute question à laquelle le message de l'utilisateur ou le projet ouvert répond déjà. Proposez d'abord une option recommandée, marquée "(Recommandé)".

Posez les questions suivantes. L'outil peut contenir jusqu'à 4 questions, donc lorsque la source est le matériel de l'utilisateur et qu'une cinquième question est nécessaire, posez la dernière dans un second appel.

• Source : ce que les fiches couvrent. Options telles que : du matériel qu'ils ont déjà (fichiers ou dossier : PDF, diapositives, notes Word ou Markdown, un cours, un dépôt, ou des flashcards existantes), ce dépôt, un sujet issu de votre propre connaissance, ou des notes qu'ils colleront. Si la demande nomme déjà la source, sautez cette question.
• Degré de fidélité (uniquement lorsque la source est leur matériel) : uniquement ce que dit le matériel (Recommandé), le matériel plus les bases manquantes marquées comme ajoutées, ou le matériel comme point de départ.
• Audience et profondeur : débutant (une idée par fiche, mots simples), intermédiaire (concepts plus un court exemple de code), ou avancé (compromis, cas limites).
• Nombre maximum de fiches : jusqu'à 10 (un ensemble rapide), jusqu'à 20 (Recommandé), jusqu'à 40 (un cours complet), ou sans limite (autant que le matériel le nécessite). L'utilisateur peut saisir n'importe quel autre nombre. Enregistrez-le comme deck(..., max_cards=N) : la construction s'arrête si le jeu dépasse cette limite, donc diviser des fiches ultérieurement ne peut pas silencieusement briser la limite. Plus de fiches signifie plus de thèmes, pas des fiches plus longues.
• Sorties : uniquement les images de fiches et les PDF (Recommandé), plus les vidéos, plus les vidéos et les vignettes. Les vidéos viennent après que les fiches sont approuvées, quoi qu'il en soit.

Ensuite, si encore inconnu, demandez en texte brut (pas besoin d'outil) : le titre du jeu affiché sur chaque fiche (par exemple "FastAPI" ou "Kubernetes"), où enregistrer la sortie (suggérez un dossier flashcards/ dans le projet actuel, ou un nouveau dossier), et si les exemples de code peuvent nommer le projet source ou doivent rester génériques. Pour le matériel de l'utilisateur, demandez aussi si chaque fiche doit indiquer d'où elle provient (par exemple "Ch. 3, p. 42").

2. Planification

Lisez d'abord la source. S'il s'agit du matériel déjà fourni par l'utilisateur, lisez maintenant references/existing-material.md : il couvre la lecture des PDF, diapositives, fichiers Word, dossiers et flashcards existants, le mappage de tout le matériel pour que rien ne soit silencieusement omis, la fidélité au matériel, et le renvoi de chaque fiche à sa page. Pour un sujet issu de votre propre connaissance, décidez ce dont un apprenant au niveau choisi a besoin. Proposez ensuite le jeu sous forme d'une courte liste : thèmes dans l'ordre d'apprentissage, et sous chacun, une ligne par fiche avec sa question. Regroupez par concept (bases HTTP, validation, authentification), pas par fichier. Visez 3 à 9 fiches par thème. Un petit jeu (moins d'environ 12 fiches) peut convenir avec 2 ou 3 thèmes de 2 à 4 fiches.

Respectez le nombre maximum de fiches et laissez de la place pour une ou deux divisions. Si le matériel nécessite plus de fiches que le maximum ne le permet, couvrez d'abord les idées centrales, puis listez les thèmes ou sections laissés de côté, et proposez d'augmenter la limite.

Montrez le plan et demandez un accord, des modifications ou des coupes avant d'écrire les fiches. Écrire 40 fiches sur les mauvais thèmes fait perdre le plus de temps, donc cette vérification vaut un aller-retour.

3. Fiches

Écrire deck.py, d'abord le premier thème

Copiez references/deck_template.py à côté de l'emplacement de la sortie. Écrivez les fiches du premier thème, générez le rendu de ce seul thème (--topic 1), montrez deux ou trois fiches à l'utilisateur et demandez si le style et la profondeur conviennent. Écrivez ensuite le reste. Découvrir à la fiche 3 que l'utilisateur voulait des fiches plus courtes est peu coûteux ; le découvrir à la fiche 40 ne l'est pas. Lisez references/components.md avant d'écrire la première fiche : il montre chaque bloc de construction (phrase d'accroche, boîtes, étapes, tableaux, exemples de code, encadrés, diagrammes) avec le HTML à utiliser.

Comment écrire une bonne fiche, et pourquoi :

• D'abord le concept. La question et la phrase d'ouverture (le lead) énoncent l'idée générale en termes applicables partout. Le code spécifique au projet va dans une boîte example(...) intitulée "Exemple : ...", afin que le lecteur apprenne la règle, puis voie un cas. Lorsque l'exemple du projet diffère de la pratique courante, dites-le dans le commentaire de l'exemple.
• Une idée par fiche. Une question qui joint deux idées distinctes ("Qu'est-ce que X, et comment le déployer ?") nécessite deux fiches. Une comparaison ("En quoi X est-il différent de Y ?") ou une paire qui n'a de sens qu'ensemble constitue une seule idée.
• Phrase d'accroche, puis structure, puis exemple. Une réponse d'une ou deux phrases, puis deux ou trois boîtes, étapes, ou un petit tableau qui la décomposent, puis un encadré facultatif et un exemple de code. Le lecteur devrait obtenir la réponse à partir de la seule phrase d'accroche.
• Le pied de page est la ligne à retenir, moins de 15 mots. L'étiquette est un ou deux mots nommant l'idée.
• Formulation simple et exacte. Phrases courtes. Nommez les vrais codes d'état, noms de fonctions et commandes ; ne les suggérez pas.
• Diagrammes uniquement là où ils ajoutent quelque chose : un flux, une décision avec des chemins d'échec, ou les parties d'une URL ou d'un message. Pas sur les fiches dont le tableau montre déjà la structure.
• Les références croisées indiquent où regarder : "La fiche 4 dans la structure de l'application montre le côté serveur."

Générer le rendu et vérifier

python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR             # chaque fiche, PDF, README
python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR --topic 1   # un thème, vérification rapide

<skill-dir> est le dossier dans lequel se trouve ce SKILL.md. Utilisez python3, ou python si c'est Python 3. Le script nécessite Python avec playwright et Pillow (pip install playwright pillow), ainsi que Google Chrome ou playwright install chromium. Il génère le rendu de chaque fiche en PNG paysage A4 de 2400 x 1698 px, vérifie que le contenu de chaque fiche tient (hauteur et largeur), et arrête de nommer toute fiche qui ne tient pas. Ensuite, il écrit un PDF par thème, print/all-cards.pdf, et README.md.

• Contenu répété : la vérification de taille mesure la taille, pas le sens. Recherchez une boîte qui répète une étape ou la phrase d'accroche, et supprimez-la.
• Dépassement du maximum : la construction s'arrête si le jeu a plus de fiches que max_cards. Fusionnez ou supprimez les fiches les moins importantes, ou demandez à l'utilisateur d'augmenter la limite. Ne l'augmentez pas de votre propre chef.
• Une fiche ne tient pas : raccourcissez le texte, supprimez une boîte, ou divisez-la en deux fiches (par exemple "9a" et "9b", ou deux questions). Ne réduisez jamais la police pour la faire entrer ; les fiches doivent rester lisibles une fois imprimées.
• Examinez chaque fiche après le rendu, en ouvrant les PNG. La vérification de taille détecte les débordements, pas une fiche confuse, un diagramme trompeur ou une faute de frappe. Corrigez et regénérez le rendu ; --topic N regénère le rendu d'un thème rapidement.
• L'espace libre est normal. La construction signale l'espace libre en px CSS sur la carte de 1200 x 849 (le PNG est deux fois plus grand). Une fiche simple laisse souvent 150 à 350 px vides, et cela convient pour la lecture et l'impression. Ne remplissez pas une fiche pour la combler. Si une fiche laisse plus d'environ 400 px et donne l'impression d'être légère, elle peut mériter un diagramme ou un exemple, ou peut être fusionnée avec une fiche voisine.

4. Extras : vidéos, vignettes, publication

Uniquement lorsque l'utilisateur les souhaite, et après qu'il a approuvé les fiches. Demandez quel style de vidéo, et dites approximativement combien de temps l'encodage prend (environ 15 secondes d'encodage par fiche sur un ordinateur portable).

python3 <skill-dir>/scripts/build_videos.py deck.py --cards OUT_DIR --out VIDEO_DIR [--mode both|questions|cards]
python3 <skill-dir>/scripts/build_thumbnails.py deck.py --cards OUT_DIR --out VIDEO_DIR/thumbnails [--mode both|questions|cards]

• --mode both (par défaut) : chaque question avec la réponse cachée et une barre de temps (6 s), puis la fiche complète (12 s).
• --mode questions : un quiz, chaque question pendant 10 s, sans réponses.
• --mode cards : une révision, chaque fiche complète pendant 15 s.
• Chaque mode produit une vidéo par thème et une avec toutes les fiches, nommées avec le mode (-questions, -cards) afin que les styles ne s'écrasent jamais. Passez le même --mode à build_thumbnails.py pour que ses noms correspondent.
• Chaque vidéo a un écran d'introduction et des écrans de titre de thème, ainsi qu'une description .txt dont les chapitres YouTube transforme en sections cliquables. Les chapitres durent au moins 10 secondes, ce qu'exige YouTube.
• Les vidéos nécessitent ffmpeg. Conservez VIDEO_DIR en dehors de tout dépôt git, car les vidéos sont volumineuses.
• Les vignettes sont des JPEG de 1280 x 720 nommés pour correspondre à chaque vidéo. topic(..., hook="A · B · C") définit la petite ligne sous le titre de chaque thème.
• Après la construction, proposez des titres et descriptions prêts pour YouTube : un titre de moins de 70 caractères avec le sujet et l'accroche, une description avec la phrase d'ouverture, une puce par thème, les liens éventuels, et les chapitres du fichier .txt.

Demandez avant de pousser, publier ou télécharger quoi que ce soit ; ces actions atteignent d'autres personnes. Si les exemples de code du jeu proviennent du cours ou du dépôt de quelqu'un d'autre, mentionnez-le avant de le rendre public et proposez une ligne de crédit (deck(..., credit="...") en place une dans le README).

Modifier un jeu ultérieurement

Modifiez deck.py et exécutez à nouveau build_deck.py ; il reconstruit chaque fiche, les PDF et le README, et supprime les images des fiches supprimées. Reconstruisez les vidéos uniquement si l'utilisateur souhaite les mettre à jour, et --descriptions-only réécrit uniquement les descriptions vidéo.

Fichiers de cette compétence

• scripts/build_deck.py : fiches, vérification de taille, PDF, README.
• scripts/build_videos.py, scripts/build_thumbnails.py : les extras.
• scripts/flashcards/ : les assistants importés par deck.py (__init__.py), le moteur de rendu (engine.py), et la feuille de style des fiches (card.css : adaptée à l'impression, blanc avec contours colorés, paysage A4 fixe).
• references/components.md : chaque bloc de construction d'une fiche avec un exemple. À lire avant d'écrire des fiches.
• references/deck_template.py : un petit jeu fonctionnel à copier.
• references/existing-material.md : construction d'un jeu à partir des propres notes, PDF, diapositives, dépôt ou flashcards de l'utilisateur. À lire lorsque c'est la source.