adamaiken89/learn-something

Cadre Apprendre Quelque Chose

Transformez un sujet en un programme structuré via une session interactive avec un LLM. Étudiez via la ligne de commande : lisez les leçons, expliquez, faites des QCM, répétez avec espacement.

1. Pédagogie

Trois théories fusionnées :

Théorie	Rôle de l'IA	Problème résolu
Marva Collins	Tuteur socratique. Q&R rigoureuses, grandes attentes, patience infinie	Nécessite un bon professeur. L'IA ne se lasse jamais.
Technique Feynman	Détecteur de lacunes. L'apprenant explique simplement → l'IA trouve les trous	Illusion de compréhension
Difficultés désirables	Planificateur d'espacement. Récupération FSRS + pratique entrelacée	Relecture passive

Phase de session → correspondance théorique

Phase	Théorie	Apprenant	IA/CLI
Lire	Marva	Étudier la leçon	Rédiger un contenu clair
Expliquer	Feynman	Expliquer le concept simplement	Sonder : "tu as dit X, mais Y — réconcilie"
S'entraîner	Marva + Désirable	Répondre aux QCM, justifier	Noter, expliquer les distracteurs
Juger	Marva	Critiquer, se faire une opinion	Suivi socratique
Réviser	Désirable	Rappel actif via FSRS	Planifier les intervalles optimaux

Budget de temps

• Sujet : 40h max (13 sem × 3h/sem)
• Module : 1.5-3h, ~15-20 par sujet
• Révision SRS : ~10-15 min par jour

2. Structure du contenu

<sujet>/
├── syllabus.yaml             # Spécification du cours
├── modules/
│   ├── NN-nom/
│   │   ├── lesson.md         # Contenu principal + exercices
│   │   ├── quiz.yaml         # 8-10 QCM
│   │   └── cloze.yaml        # 8-10 questions à trous
│   └── ...
└── srs/
    ├── deck.json             # Cartes FSRS-5
    └── stats.json            # Historique

Modèles complets dans templates/. Clés : syllabus.yaml (squelette de 20 modules), module.md (structure de leçon), quiz.yaml (format QCM à 4 options).

3. Protocole de création de contenu

Flux de travail

1. Cadrage (5 min) : Demander domaine/niveau/budget de temps/langue/cas d'utilisation. Proposer un syllabus.
2. Phase de planification : Vérifier le DAG des modules + la chaîne de prérequis. Vérifier le budget de temps. 3. Par module (10 min) : Créer un module avec learn.sh create-module <sujet> NN-nom. Nom en kebab-case avec deux chiffres zéro-padding (ex. 01-intro, 02-concepts-fondamentaux). Rédiger lesson.md + quiz.yaml. Appliquer 16 règles de qualité en ligne. Garder lesson.md ≤12 000 caractères. Si le contenu déborde, diviser en modules supplémentaires et mettre à jour le syllabus. L'utilisateur révise. Continuer. 3.5. Valider la syntaxe : Exécuter learn.sh validate-content <sujet> [module]. Corriger toutes les erreurs markdown + mermaid avant de continuer.
3. Pré-publication : Charger content-verify.md. Exécuter la liste de contrôle. Corriger les violations.
4. Compiler le SRS (2 min) : Extraire les QCM → deck FSRS-5.
5. Quiz cumulatifs : Après chaque 3-5 modules, générer cumulative_quiz.yaml à la racine du sujet. 8-10 questions mélangeant QCM à trous, QCM, V/F. Chacune étiquetée avec source_modules. Réponses réparties sur A-D.

Principes de contenu

• Alignement CILO : Chaque module sert ≥1 objectif d'apprentissage. Pas de remplissage.
• Langue : Tout le contenu dans la langue du syllabus.yaml (en/zh/yue).
• Pratique d'abord : Commencer par un exemple concret avant la définition abstraite.
• Pertinent pour le domaine : Scénarios issus du secteur de l'apprenant.
• Suppressions à trous : Chaque module reçoit 3-5 blancs à trous ({terme}). L'apprenant remplit avant de continuer. Force la récupération pendant la lecture.
• Prédire la suite : Chaque chaîne causale reçoit 2-3 blocs de prédiction. L'apprenant s'engage sur le résultat avant la révélation.
• Repérer les erreurs : Chaque module reçoit 1-2 exercices "Repérez l'erreur". L'apprentissage par l'erreur développe les compétences de diagnostic.
• Double codage : Chaque concept reçoit un diagramme (Mermaid, ascii, ou hiérarchie structurée).
• Diversité des QCM : 40% de mémorisation, 40% d'application, 20% en plusieurs étapes.
• Invite Feynman : Chaque leçon se termine par une tâche d'explication + une sonde IA pour les lacunes.
• Difficulté désirable : Le même concept est testé sous différents angles dans tous les modules.
• Budget de temps : Module ≤3h. Sujet ≤40h.
• Limite de taille du module : Chaque lesson.md de module ≤12 000 caractères. Dépassement ? Diviser le sujet en plus de modules. Ajuster le nombre de modules du syllabus en conséquence.
• Progression : Se baser sur les prérequis. Les premiers modules sont fondamentaux.
• Saut autorisé : L'apprenant donne des informations éparses ? Générer le contenu avec des valeurs par défaut raisonnables. Ne pas bloquer.
• Socratique tout au long : Chaque concept majeur est suivi d'une question qui fait réfléchir l'apprenant — pas seulement à la fin du module, mais en ligne après chaque nouvelle idée. Question → brève réponse/explication juste après pour que l'apprenant puisse s'auto-vérifier. Modèle : énoncer le concept → demander "pourquoi ?" ou "et si ?" → répondre.
• Diagrammes Mermaid : Pour les concepts avec logique de branchement, machines d'état, flux de travail ou chaînes causales : générer un diagramme Mermaid (organigramme, séquence, état). Le thème injecte automatiquement neutral pour la compatibilité sombre/clair. Utiliser une palette de couleurs terreuses douces pour les remplissages style — visibles dans les thèmes sombre et clair. Palette : bleu #5c7a99, vert #5c8a6a, orange #b8924a, rouge #b86a4a, violet #7a5a8a, gris #888. Traits : utiliser une teinte plus foncée du remplissage ou #333. Exemple : style A fill:#5c7a99,stroke:#333. Placer après l'explication du concept, avant la question Pense.
• Carte mentale du module : Chaque module reçoit une carte mentale Mermaid en haut de lesson.md (après les métadonnées, avant les Objectifs d'apprentissage). Montre la hiérarchie des connaissances : concept central → sujets clés → sous-concepts. Utiliser la syntaxe mindmap. Maximum 3 niveaux de profondeur.
• Répartition des réponses : Les clés de réponse des QCM doivent être réparties sur A/B/C/D. Pas plus de 2 questions consécutives partagent la même lettre de réponse. Le modèle montre B comme exemple — faire tourner lors de la génération.
• Quiz cumulatifs : Après chaque 3-5 modules, générer cumulative_quiz.yaml à la racine du sujet. 8-10 questions mélangeant QCM à trous, QCM, V/F. Chaque question étiquetée avec source_modules. Réponses réparties sur A-D.

Règles de qualité du contenu (16)

#	Règle	Que faire	Mauvais exemple → Bon exemple
1	Expliquer les conventions	Expliquer pourquoi la convention existe, pas seulement ce qu'elle est	"Prix coté 95" → "95 = 95% de 1 000 $ de valeur nominale. La convention de % permet la comparaison entre obligations de valeurs nominales différentes."
2	Répondre aux Q implicites	Anticiper 1 à 3 questions que l'apprenant n'a pas posées	"Silence sur les coupons" → "Le coupon change-t-il jamais ? Non pour les taux fixes. Oui pour les obligations à taux variable (se réinitialise périodiquement)."
3	Intuition du retour à la valeur	Expliquer que le prix converge mécaniquement vers la valeur nominale à l'échéance	"Le prix converge vers le pair car le temps rétrécit + la valeur actualisée des CF restants converge vers le principal. Pas piloté par les taux."
4	Chaîne causale d'abord	Logique intuitive avant la formule	Sauter directement à la formule de tarification → "Les nouvelles obligations paient 6 %. Mon obligation paie 4 %. La mienne a moins de valeur → le prix baisse jusqu'à ce que le rendement corresponde."
5	Contexte pratique	Chaque nombre a une signification réelle	"Duration 7,5" → "Une hausse de taux de 1 % → baisse de prix d'environ 7,5 % (petits mouvements uniquement ; ajustement de convexité pour les grands)."
6	"Probabilité"	Indiquer les fréquences normales vs rares	Omission → "La courbe des taux s'inverse rarement. Chaque inversion a précédé une récession (~8 mois). Pas parfaitement prédictif."
7	Idées reçues courantes	Signaler 1 à 2 erreurs spécifiques que les débutants ont	"Coupon élevé = meilleure obligation" → "Non. Les obligations à escompte ont un gain de prix intégré à l'échéance (accrétion)."
8	Socratique tout au long	Chaque section de concept intègre une question Pense + réponse immédiate	L'apprenant lit passivement → est obligé de s'arrêter et de traiter

...

[abrégé pour la traduction]