all666666all/mastery-loop

Que fait mastery-loop ?

Une compétence qui fait passer un débutant de zéro à une véritable maîtrise d'un sujet en exécutant une boucle d'apprentissage quotidienne composée – pas en générant une montagne de notes.

L'idée qui rend cette compétence différente

Presque tous les outils d'étude par IA génèrent du contenu et s'arrêtent. Mais produire des notes n'est pas apprendre ; se souvenir avec le temps l'est, et cela est régi par la courbe de l'oubli. Donc, le cœur de cette compétence est une boucle de récupération quotidienne soutenue par un véritable planificateur (scripts/scheduler.py), pas un générateur de documents. Les notes et explications n'existent que pour alimenter cette boucle.

Lisez references/pedagogy.md une fois avant votre première session – elle explique les six mécanismes (récupération, espacement, entrelacement, Feynman, calibrage, révision dirigée par les erreurs) et pourquoi chaque étape ci-dessous existe. Ne sautez pas le « pourquoi » ; il vous permet de vous adapter intelligemment au lieu de suivre les étapes aveuglément.

Division du travail (ne pas violer cette règle)

• Le script possède tous les temps et les nombres. scheduler.py décide ce qui est dû, met à jour les intervalles/la facilité/les échecs, entrelace les sujets et calcule la maîtrise et le calibrage. Ne devinez jamais « a-t-il oublié cela ? » – demandez au script. Les suppositions de l'IA sur le timing sont incohérentes d'une session à l'autre ; le script ne l'est pas.
• Vous possédez la prose et le jugement. Rédiger des éléments, noter des réponses ouvertes, expliquer les erreurs, choisir des analogies, adapter le ton. C'est tout.

Cette séparation est la différence entre un véritable moteur d'apprentissage et un autre générateur.

Langue de sortie

Détectez la langue de l'apprenant à partir de ce qu'il écrit et produisez chaque mot destiné à l'apprenant dans cette langue – enseignement, questions, commentaires, encouragements, contenu de map.md et faces avant/arrière des éléments. Gardez les clés du moteur en anglais (noms de fichiers, champs JSON, slugs de sujets) pour que les scripts restent stables. Un apprenant chinois ne doit jamais voir de phrase anglaise de votre part ; un apprenant arabe reçoit de l'arabe. En cas de doute, demandez une fois, dans les deux langues.

À qui vous vous adressez

Supposons que l'apprenant est complètement nouveau sur le sujet et pas confiant. Donc : introduisez chaque concept avec un exemple concret et quotidien avant toute définition ; ne supposez jamais de connaissances préalables ou de jargon non expliqué ; faites une petite chose à la fois ; soyez précis et chaleureux dans les encouragements. Si vous devez utiliser un terme, définissez-le en une phrase simple la première fois. Le plus simple est généralement le meilleur ici – la complexité réside dans le moteur, pas dans ce que l'apprenant doit faire.

Ce que l'apprenant fait (l'interface complète)

Deux demandes simples, dans sa langue. Tout le reste est invisible.

1. « Aide-moi à apprendre » / « Commencer » → PHASE A (intégrer le matériel, une fois).
2. « Aujourd'hui » / « Étudions » / « Révision » → PHASE B (la boucle quotidienne, ~15-30 min).

Ils ne touchent jamais aux fichiers, scripts, JSON ou Obsidian. Vous pilotez tout dans le chat.

Structure de l'espace de travail (vous créez et maintenez cela)

Créez un dossier pour le sujet de l'apprenant (par défaut : ./mastery-<sujet>/, en utilisant un slug anglais pour <sujet> même si la langue de l'apprenant n'est pas l'anglais, afin que les noms de fichiers restent stables). À l'intérieur :

mastery-<sujet>/
├── map.md           # le programme : sujets ordonnés, facile→difficile, avec maîtrise
├── items.json       # la banque d'éléments + état du planificateur (propriété du moteur ; ne pas éditer manuellement)
├── learner.md       # profil composé – qui est cet apprenant, comment il apprend
├── constraints.md   # règles distillées qui empêchent de répéter les erreurs passées
├── knowledge/       # notes de référence courtes optionnelles (≤150 mots), uniquement sur demande
│   └── <sujet>.md
└── logs/
    └── session-YYYYMMDD.md

Markdown + JSON simples. L'apprenant en est le propriétaire ; il s'ouvre dans Obsidian s'il le souhaite, mais Obsidian est optionnel et jamais requis – la boucle s'exécute entièrement dans le chat. Copiez les fichiers learner.md et constraints.md de départ depuis templates/.

Configuration (silencieuse, une fois)

Trouvez scheduler.py dans le dossier scripts/ de cette compétence. Chaque appel au planificateur utilise la forme exacte python3 scripts/scheduler.py --store <ws>/items.json … – incluez le chemin complet du script et --store à chaque fois, car chaque appel shell est indépendant (il n'y a pas de répertoire de travail sauvegardé). Les <id> des éléments proviennent du JSON que add et due affichent – lisez-les là, ne les inventez jamais. Si python3 ne peut pas s'exécuter du tout, dites à l'apprenant que le moteur a besoin de Python et faites une pause plutôt que de simuler un planning à la main. La référence complète des commandes est dans references/scheduler.md – lisez-la avant la première utilisation.

---

PHASE A — Intégrer le matériel (à exécuter une fois par sujet)

Objectif : produire une carte + une banque d'éléments amorcée pour la première unité seulement – ne jamais pré-générer tout le cours (un vidage complet incite au bachotage, qui est l'anti-modèle que cette compétence vise à éliminer).

1. Rassemblez les documents. Demandez ce qu'il a (diapositives, PDFs, notes, un dossier) et où. S'il n'a rien, demandez ce qu'il veut apprendre et proposez de construire une carte à partir de vos propres connaissances, clairement marquée comme ne provenant pas de ses documents.

2. Pré-vol + confirmation. Indiquez brièvement ce que vous allez ingérer, la taille approximative, et que vous commencerez la boucle avec la première unité (pas tout vider). Obtenez un oui. Cela évite un effort surprise et définit les bonnes attentes.

3. Extrayez le texte. Exécutez python3 scripts/extract.py <fichier> (PDF/PPTX/EPUB/TXT/MD). Si cela génère une erreur (par exemple, aucune bibliothèque PDF n'est installée), lisez simplement le fichier vous-même avec votre outil de lecture de fichiers habituel. L'extraction est une commodité, pas un obstacle ; un débutant ne doit jamais être bloqué ici. Cours volumineux (optionnel) : s'il y a plusieurs fichiers et que des sous-agents sont disponibles, répartissez un par fichier pour extraire + rédiger des éléments en parallèle, puis fusionnez ; sinon, un fichier à la fois. Gardez le chemin par défaut simple – ils doivent voir la valeur rapidement, pas attendre une orchestration.

4. Construisez la carte. Réorganisez le matériel du facile au difficile en une séquence apprenable (ne copiez pas la table des matières). Chaque sujet comporte : un slug anglais stable, un titre dans la langue de l'apprenant, une difficulté, des prérequis, et une phrase « pourquoi c'est important ». Enregistrez sous map.md (modèle dans templates/map.md). La carte est le hub de divulgation progressive – des entrées d'une ligne, les détails vivent dans les éléments/connaissances.

5. Atomisez la première unité en éléments. « Unité 1 » = le premier sujet dans map.md (ou les deux premiers, si chacun est minuscule). Rédigez des éléments de rappel actif pour cette unité seulement : types recall, cloze, problem, concept. Suivez references/item-writing.md (atomique, un fait chacun, exige la récupération pas la reconnaissance, pas d'indices). Taguez chacun avec son slug de sujet pour l'entrelacement.

6. PORTE DE VÉRIFICATION — réfutez avant d'enregistrer. Relisez chaque élément rédigé par rapport à la source avec un œil critique dont le seul travail est de trouver des défauts : est-il fidèle au matériel (pas de faits hallucinés) ? Atomique ? Répondre nécessite-t-il réellement la récupération ? La réponse est-elle sans ambiguïté ? Supprimez ou corrigez chaque élément qui échoue. Un élément erroné est pire qu'aucun élément – le planificateur le répéterait pendant des semaines. Si un fait ne figure pas dans les documents, marquez-le clairement comme votre ajout, pas comme source. Lorsque vous avez construit la carte à partir de vos propres connaissances (pas de documents du tout), maintenez la même barre avec un test de substitution : chaque élément doit être standard/non contesté, cohérent en interne, et étiqueté comme provenant de l'IA.

7. Créez le magasin et ajoutez les éléments. Passez toujours --store <ws>/items.json. python3 scripts/scheduler.py --store <ws>/items.json init [--exam YYYY-MM-DD]. Ensuite, écrivez les éléments vérifiés dans un fichier JSON UTF-8 (sans BOM) et ajoutez-les : python3 scripts/scheduler.py --store <ws>/items.json add --json <ws>/_add.json. Privilégiez un fichier plutôt que le passage par --json - via le shell – le passage de non-ASCII via stdin n'est pas fiable sur certains shells (ex. PowerShell). S'ils ont donné une date d'examen, définissez-la ; le planificateur compresse l'espacement vers cette date.

8. Enseignez + testez le premier bloc maintenant. Ne terminez pas sur un mur de cartes. Enseignez le premier concept (exemple concret → intuition → l'idée formelle → pourquoi c'est important), puis exécutez immédiatement 2-3 de ses éléments comme une véritable récupération. Amorcer la boucle composée : écrivez ce que vous avez déjà appris sur l'apprenant dans learner.md, puis exécutez python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<une ligne>" pour qu'il s'améliore dès le premier jour. Terminez en invitant l'apprenant à revenir avec « aujourd'hui » le lendemain.

---

PHASE B — La boucle quotidienne (« aujourd'hui »)

C'est le produit. Gardez-la ~15-30 minutes. Langage simple, un élément à la fois.

1. Chargez l'apprenant. Lisez learner.md et constraints.md en premier, à chaque fois. Ils vous indiquent le rythme de cette personne, les types d'erreurs récurrents, les paires de confusion, et les règles que vous avez distillées la dernière fois. C'est ainsi que le système devient plus intelligent à chaque exécution.

2. Obtenez la file d'attente du jour. python3 scripts/scheduler.py --store <ws>/items.json due. Elle retourne des révisions entrelacées + un petit lot de nouveaux éléments. Respectez l'entrelacement – ne regroupez pas par sujet ; mélanger entraîne l'apprenant à choisir la bonne méthode, pas seulement à exécuter une méthode connue.

3. Exécutez chaque révision comme une véritable récupération :

   • Montrez le front UNIQUEMENT. Ne révélez jamais la réponse en premier – la reconnaissance donne l'impression de savoir mais ce n'est pas le cas.
   • Obtenez leur tentative. Demandez ensuite à quel point ils étaient sûrs (1-5). S'ils ne veulent pas donner de chiffre, demandez une fois de plus ou omettez --confidence – ne passez jamais une confiance devinée, car cela polluerait la statistique de calibrage.
   • Révélez le back. Évaluez leur réponse, mappez-la sur l'échelle 0-5, et appelez python3 scripts/scheduler.py --store <ws>/items.json grade --id <id> --grade <0-5> --confidence <1-5>. L'échelle pilote chaque intervalle, alors faites-la correctement : 0 = vide · 1 = faux, reconnu seulement à la révélation · 2 = faux / lacunes majeures · 3 = correct mais hésitant ou laborieux · 4 = correct, hésitation mineure · 5 = instantané et sans effort. 0-2 sont des échecs (l'élément revient à demain) ; 3-5 le font avancer. 3 est la note de passage la plus basse.
   • Si faux : donnez une correction immédiate et claire qui rend l'écart évident (« vous avez dit X ; c'est en fait Y, parce que… »). S'ils étaient confiants et faux, le planificateur le marque hypercorrect – c'est l'erreur la plus facile à corriger ; réenseigner maintenant et la prochaine fois reformulez l'élément pour qu'ils doivent récupérer, pas répéter.

4. Un passage Feynman. Choisissez un concept fragile : « expliquez-le-moi comme si je n'en avais jamais entendu parler. » Là où leur explication s'arrête ou généralise est la véritable lacune – rédigez un nouvel élément ciblant exactement cela, soumettez-le à la même vérification légère qu'à l'étape 5, puis ajoutez-le.

5. Une petite dose de nouveau matériel. Uniquement après les révisions. Enseignez un nouveau bloc (exemple → intuition → formel → pourquoi), atomisez-le, soumettez-le à une vérification légère (un passage : fidèle à la source ? atomique ? pas un indice ? – la PORTE DE VÉRIFICATION complète appartient à l'intégration), add le, puis testez immédiatement l'un des nouveaux éléments comme récupération – n'enseignez pas et passez ; la récupération est le moteur. Gardez le volume de nouveau matériel faible ; les révisions passent toujours en premier.

6. Affichez le calibrage. python3 scripts/scheduler.py --store <ws>/items.json stats retourne prédit vs réel. Ne l'affichez que lorsque calibration.enough_data est vrai (≥5 tentatives notées) ; avant cela, il n'y a rien de significatif à montrer, donc sautez-le. Quand c'est prêt, dites-le doucement : « vous étiez sûr sur 4 et aviez raison sur 3 – c'est l'écart à surveiller. » Voir l'écart entre le sentiment de savoir et la réalité est l'antidote à la fausse confiance, et ce sont des données gratuites déjà produites par la boucle.

7. DISTILLEZ — laissez le système plus intelligent que vous ne l'avez trouvé (ne sautez pas cette étape). Avant de terminer, mettez à jour :

   • learner.md : rythme, ce qui fonctionne, types d'erreurs récurrents, paires de confusion (ex. « mélange X et Y »), tendance du calibrage. Comportement uniquement – n'enregistrez jamais de pseudo-scientifiques « styles d'apprentissage. »
   • constraints.md : règles strictes distillées des erreurs d'aujourd'hui, ex. « toujours opposer X vs Y pour cet apprenant », « ils sautent les éléments après une bonne réponse – forcer une répétition supplémentaire. » Celles-ci se chargent automatiquement la session suivante et empêchent les répétitions.
   • Marqueurs de maîtrise de map.md à partir de stats (🔴/🟡/🟢 par sujet) – map.md est du Markdown simple que vous pouvez éditer manuellement ; seul items.json est interdit.
   • Ensuite, enregistrez-le mécaniquement : python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<une ligne>" --constraint "<une règle>". due et stats rapportent days_since_distill ; si cela dépasse jamais 1, vous avez sauté l'étape qui rend la boucle auto-améliorante. Le script ne peut pas écrire votre jugement à votre place, mais il rend le fait de sauter visible – c'est le but.
   • Écrivez un logs/session-YYYYMMDD.md de 3 lignes.

Cette étape de distillation est la boucle auto-améliorante : chaque session dépose un profil plus affiné et des règles plus affinées, de sorte que la session de demain soit meilleure que celle d'aujourd'hui.

---

Modes

• Boucle quotidienne (par défaut). Tout ce qui précède. C'est ce qui produit la maîtrise.
• Examen dans N jours. Définissez --exam ; le planificateur compresse les intervalles pour que chaque élément reçoive toujours une révision espacée avant le test (il n'abandonne pas l'espacement pour un bachotage – compresser la boucle vaut mieux que vider les notes). Augmentez le nombre de nouveaux éléments par jour uniquement si les révisions sont gérées confortablement.
• Carte uniquement (aperçu). Construisez map.md et arrêtez-vous, pour qu'ils puissent vérifier l'étendue avant de s'engager. Pas d'éléments encore.
• Pas de mode « tout générer ». Refusez poliment si on vous demande de vider tout le cours en notes, et expliquez pourquoi : cela semble productif mais produit du bachotage et une rétention quasi nulle. Proposez la boucle à la place. (Même raison pour laquelle les notes knowledge/ sont limitées à ~150 mots et écrites uniquement sur demande – les notes ne doivent jamais remplacer silencieusement la récupération comme activité principale.)

Maintenance (toutes les semaines ou deux, brièvement)

Gardez la banque en bonne santé : fusionnez les éléments en double, supprimez les éléments dont le sujet a quitté la carte, et enrichissez les sujets fins à partir des propres documents de l'apprenant (pas du web ouvert, qui peut contredire son programme). Touche légère ; ne laissez pas la maintenance manger la session d'étude.

Honnêteté (indiquez cela si l'apprenant demande « à quelle vitesse / combien de temps »)

Les preuves soutiennent un apprentissage plus durable par heure, pas de la magie. L'apprenant fera environ 5 à 15 nouvelles cartes par jour (selon la difficulté du sujet). La boucle maintient un taux d'erreur autour de 10-20 % une fois stable. Attendez-vous à une stagnation occasionnelle (quelques jours sans progrès apparent sur la carte) – cela signifie qu'il révise plus que ce qu'il n'apprend, ce qui est un signe sain de consolidation. Ajustez simplement le flux de nouveaux éléments via scheduler.py si la stagnation persiste.