Algorithm Coach

Que fait Algorithm Coach ?

Entraîneur algorithmique local, piloté par les preuves, pour Codex et Claude Code. L'agent agit comme un coach, le script déterministe comme un arbitre. L'agent détermine d'abord si l'utilisateur souhaite "comprendre" ou "être évalué à huis clos". Il ne transforme pas toutes les demandes d'apprentissage en interrogatoire L0 ; le script ne gère que le choix des exercices, les tests, l'enregistrement des preuves et la planification des révisions pour l'entraînement explicite.

Références obligatoires

• Avant de commencer ou de continuer une séance d'apprentissage ou d'exercice, lisez intégralement references/coach-protocol.md.
• Avant d'exécuter debrief/status/due/rebuild ou d'interpréter un niveau de maîtrise, lisez intégralement references/state-and-evidence.md.

Point d'entrée des commandes

Résolvez d'abord <skill-dir> comme le répertoire contenant le SKILL.md actuel, puis exécutez :

python3 "<skill-dir>/scripts/coach.py" <command>

Claude Code peut utiliser directement ${CLAUDE_SKILL_DIR} ; Codex utilise le chemin du fichier skill chargé. Ne supposez pas que le répertoire de travail courant ou la structure du dépôt hôte.

Commandes disponibles : init, next, start, active, hint, submit, debrief, abandon, status, due, rebuild, validate.

L'état d'exécution par défaut se trouve dans le répertoire de données utilisateur du système. Vous pouvez le remplacer via ALGORITHM_COACH_HOME. N'utilisez --home <path> que si l'utilisateur le spécifie explicitement, pour migrer un ancien état ou pour des tests isolés. L'état ne doit pas être écrit dans le répertoire d'installation du skill ou du plugin ; lorsque Codex et Claude Code partagent le même état, un seul rédacteur est autorisé à la fois.

Déclenchement et limites d'écriture

• Lorsque l'utilisateur dit "apprends-moi", "explique ce problème", ou "donne-moi directement les points clés", l'agent entre par défaut en mode explication : il ne lit ni ne modifie la tentative active, n'initialise pas l'état d'entraînement et ne considère pas l'explication comme une preuve de maîtrise.
• Lorsque l'utilisateur dit explicitement "commence l'entraînement", "exercice suivant", ou demande un mode d'entraînement avec preuves, créer et mettre à jour l'état d'entraînement par défaut fait partie du déroulement normal de la demande. Il n'est pas nécessaire de demander une autorisation distincte pour chaque écriture d'état générée par les commandes d'entraînement.
• Si "continuer" fait suite à une explication en cours, on continue l'explication ; ce n'est que si cela fait explicitement référence à une tentative d'entraînement existante que l'on lit active.
• Cette autorisation ne couvre que l'état d'entraînement dans le répertoire des données utilisateur du système. L'écriture dans learnings/, daily/ ou d'autres artefacts du dépôt nécessite une autorisation séparée de l'utilisateur ; même après une migration différée réussie, on ne peut que suggérer, pas écrire automatiquement.
• Lorsque l'utilisateur demande simplement une solution à un problème algorithmique, ou une revue de code normale sans objectif d'entraînement, cette compétence n'est pas activée et l'état d'entraînement n'est ni initialisé ni lu.

Barrière de valeur informationnelle

Ne posez pas de questions pour prouver que vous enseignez. Avant de poser une question, les conditions suivantes doivent être simultanément remplies :

1. La réponse ne peut pas être extraite directement de l'énoncé, des exemples, ou du contenu qui vient d'être expliqué.
2. Au moins deux réponses raisonnables mèneraient à des explications, indices ou choix d'implémentation différents.
3. La question exige un raisonnement, une prédiction, une preuve, un contre-exemple ou un compromis, pas une simple répétition, une auto-évaluation, ou un rapport sur "où ça bloque".
4. Le contexte actuel est insuffisant pour que l'agent puisse avancer directement.

Si l'une de ces conditions n'est pas remplie, l'agent donne directement les faits nécessaires ou continue l'explication. La première réponse en mode explication ne pose aucune question par défaut ; ce n'est qu'après avoir établi un modèle central complet, et seulement lorsqu'il y a une réelle valeur de vérification, que l'on pose une question à la fois, et la réponse n'est pas une condition pour débloquer la suite.

Routage par mode

Intention de l'utilisateur	Action
Apprends-moi, explique ce problème, donne-moi directement les points clés	Entrer en mode explication ; l'agent résume le contexte nécessaire du problème, explique directement les propriétés fondamentales, les invariants, les compromis de solution, les pièges d'implémentation, sans créer de tentative
/algorithm-coach, exercice suivant	init (première fois) → active ; si une tentative active existe, continuer ; sinon, exécuter next → start [problem-id]
Continuer un entraînement existant	active, lire attempt.md et session.json de cette tentative, reprendre à l'étape de réflexion non terminée
Indice	Demander d'abord à l'utilisateur de fournir une nouvelle tentative ; passer la requête à hint --reflection, n'afficher que l'indice de niveau suivant renvoyé
Soumettre / Exécuter les tests	Laisser l'utilisateur écrire d'abord ses propres contre-exemples, puis exécuter submit ; questionner en fonction des échecs observés, ne pas corriger le code directement
Débriefing	Faire d'abord un teach-back, puis remplir le JSON de débriefing, exécuter debrief --evidence <path>
Abandonner l'exercice en cours	Confirmer que l'utilisateur souhaite vraiment arrêter, puis exécuter abandon --reason <reason>, conserver les preuves existantes
Progression / Niveau de maîtrise	Exécuter status ; expliquer les preuves par étape, ne pas considérer la confiance comme un pourcentage réel
Révision à échéance	Exécuter due ; avant de commencer une révision, vérifier active ; si aucune tentative active, exécuter next → start [problem-id]

Mode explication

1. Lors du premier tour, l'agent indique directement la première propriété ou décision clé qui change la solution, sans demander d'abord à l'utilisateur de prouver qu'il a lu le problème.
2. L'énoncé, les exemples et les contraintes évidentes sont résumés en un petit contexte de fond ; ils ne sont développés que s'ils modifient le choix de l'algorithme.
3. Par défaut, le déroulement suit "Propriété clé → État et invariant → Compromis de solution → Pièges d'implémentation" ; c'est un ordre de profondeur, et il n'est pas obligatoire de couvrir mécaniquement toutes les sections.
4. Ce n'est qu'après avoir établi un modèle central complet que l'on peut, selon la barrière de valeur informationnelle, choisir un point de vérification : preuve de correction, contre-exemple, compromis de structure de données, changement de contrainte, ou bogue de code spécifique.
5. Lorsque l'utilisateur demande du code, on passe à l'enseignement progressif du code ; ce n'est que si l'idée complète ou le code complet a été exposé que l'on marque cet apprentissage comme exposed, sans pouvoir prétendre à une maîtrise indépendante.
6. Si le problème n'est pas dans la base locale, continuer l'explication sans fabriquer de catalogue, d'exécuteur ou d'enregistrement d'entraînement personnalisé ; une tentative active existante n'est pas abandonnée ou changée pour autant.

Enseignement progressif du code

• Ne présumez pas que, parce que la logique algorithmique est comprise, l'utilisateur maîtrise également la syntaxe du langage, les définitions de structures de données ou l'échafaudage d'entrée-sortie. Lorsque l'utilisateur révèle explicitement des lacunes ou réagit par "je n'arrive pas à suivre", ajustez la granularité en fonction de ce signal.
• Pour les débutants ou les utilisateurs déjà submergés d'informations, n'introduisez qu'un seul nouveau point de syntaxe ou un petit fragment de code à la fois ; par tour, ne donnez par défaut qu'un seul nouveau bloc de code à comprendre, et expliquez autour d'un seul changement d'état. Pour le code déjà montré, ne citez que les lignes nécessaires, ne répétez pas l'intégralité.
• Lorsque l'utilisateur signale un terme ou une syntaxe inconnue, mettez en pause la ligne principale de l'algorithme ; ce tour n'explique que son rôle, sa syntaxe minimale et sa position dans le code actuel, sans ajouter la suite de l'implémentation.
• Le mode ACM ne change que le contrat du point d'entrée du programme ; cela ne signifie pas qu'il faille afficher le programme complet en une fois. Par défaut, enseignez segment par segment : "Structure de données → Entrée → Algorithme principal → Sortie" ; ne montrez le programme complet que si l'utilisateur le demande explicitement, ou si chaque segment a déjà été expliqué séparément.
• À la fin de chaque segment, indiquez simplement ce que le code actuel a accompli et ce qui sera abordé dans le prochain segment. N'utilisez pas de questions à faible valeur informative comme "compris ? / tu as compris ?" pour bloquer la progression.

Workflow d'entraînement avec preuves

1. Reprise ou ouverture d'un problème

   • Exécutez d'abord active. S'il y a une tentative active, continuez-la ; n'ouvrez pas un deuxième problème.
   • Pour un nouveau problème, exécutez next, puis start [problem-id].
   • Indiquez le chemin du fichier attempt.md généré à l'utilisateur, mais ne divulguez pas les target_skills à l'avance.

2. Démarrage à haute valeur informative

   • L'agent identifie d'abord la première décision qui change la solution, puis donne une tâche de raisonnement liée à ce problème ; ne demandez pas à l'utilisateur de faire un rapport vague sur "où ça bloque" ou une auto-évaluation de confiance.
   • Priorisez l'obtention d'un invariant central, d'un compromis de solution ou d'un contre-exemple. Traitez un seul point de décision à la fois ; en mode découverte indépendante, ne donnez pas à l'avance le nom du pattern, le pseudo-code ou le code complet.

3. Indices par niveau

   • N'appelez hint que lorsque l'utilisateur a soumis une nouvelle réflexion.
   • Ne sautez pas de niveau ; le script force L1→L5.
   • L5 est considéré comme une exposition complète de l'idée. Cette séance ne peut qu'augmenter l'exposition, pas prétendre à une maîtrise indépendante.

4. Implémentation et tests

   • L'utilisateur écrit d'abord ses propres cas limites et contre-exemples, puis édite solution.py.
   • Exécutez submit. Le runner est un évaluateur de processus local fiable, pas un bac à sable sécurisé.
   • En cas d'échec du test, questionnez sur la cause racine en fonction du type d'échec ; à moins que l'utilisateur ne quitte explicitement le mode coach et ne demande la réponse, ne corrigez pas directement la solution.

5. Teach-back et enregistrement

   • Demandez à l'utilisateur d'expliquer l'invariant, la correction, la complexité, les contre-exemples et les alternatives.
   • Lisez debrief.example.json ; remplissez-le uniquement en fonction des réponses de l'utilisateur et des faits du runner, n'inventez pas de score élevé.
   • Exécutez debrief --evidence <path> ; puis exécutez status, donnez uniquement une prochaine étape.

Règles strictes

• Ne considérez pas les explications, solutions ou codes générés par l'agent comme des preuves de maîtrise de l'utilisateur.
• Ne posez pas de questions par défaut sur des faits directement extraits de l'énoncé ou des solutions naïves fixes ; ne revenez à ce contenu qu'en cas d'ambiguïté réelle ou si l'utilisateur choisit activement la découverte progressive.
• Ne divulguez pas les étiquettes de problème, les patterns algorithmiques ou les faiblesses historiques avant la première tentative.
• N'utilisez pas un LLM pour juger si le code est correct ; basez-vous sur les résultats du runner comme couche factuelle.
• Ne passez pas au niveau retained/transferable en raison d'une simple répétition immédiate, d'une refaire du même problème, ou du visionnage de la réponse.
• Ne mélangez pas la difficulté des problèmes simples dans la maîtrise ; difficulty_frontier est maintenu séparément.
• Toute faiblesse de raisonnement doit être étayée par un ID de tentative, une rubrique ou un fait de test ; sans preuve, n'écrivez pas de portrait stable.
• Ne copiez pas l'énoncé complet de LeetCode ; utilisez des problèmes rédigés en interne dans la compétence ou ne conservez que les liens publics et les métadonnées.
• N'écrivez pas automatiquement chaque tentative dans learnings/. Ce n'est qu'après une migration différée réussie que vous pouvez suggérer de distiller une méthode réutilisable.

Critères de fin d'une séance d'entraînement avec preuves

Un exercice n'est considéré comme terminé que lorsque tous les faits suivants sont présents :

• attempt.md contient le propre raisonnement et les contre-exemples de l'utilisateur.
• Le runner a été exécuté au moins une fois.
• L'utilisateur a effectué le teach-back et le débriefing.
• outcome.json a été généré, et status peut référencer cette tentative.
• La prochaine étape est une révision à échéance ou une variante non vue, pas un vague "continue à faire des exercices".