Ustagammon/docs/adr/0011-lecons-conseil-et-bilan.md

0011. Leçons numérotées, conseil du maître après le coup, bilan de fin de partie

• Statut : accepté
• Date : 2026-11-03
• Décideurs : Pierre

Contexte

Le cadrage (docs/cadrage.md) prévoit pour la V1 un coach en direct, un écran de fin de partie et des leçons par concept, sans en fixer la forme. Les maquettes des écrans (https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe), faites avec la charte graphique (ADR 0010), en ont proposé une. Pierre en a retenu trois éléments le 2026-11-03.

Un point des maquettes contredisait le cadrage : le conseil apparaissait avant que le joueur ne joue, en donnant la réponse. Pierre a tranché pour un commentaire après le coup.

Décision

• Leçons numérotées : un parcours de leçons dans un ordre fixe (« Leçon 1 », « Leçon 2 »…). Chaque leçon affiche son état (à commencer, « 3 exercices sur 5 », terminée) et sa progression. L'accueil propose de continuer la leçon en cours.
• Conseil du maître : c'est la forme du coach en direct du cadrage. Il commente le coup après que le joueur l'a joué, jamais avant. Il donne l'appréciation du moteur avec un mot et une icône (bon coup, imprécision, erreur), puis une phrase du maître qui dit quel coup il aurait joué et pourquoi, avec un lien pour en savoir plus. L'écart d'équité n'apparaît que sur demande. Il reste désactivable, comme le prévoit le cadrage.
• Bilan de fin de partie : le résultat, le décompte des coups par appréciation (bons coups, imprécisions, erreurs), « le coup à revoir » (la plus grosse erreur, avec sa position, le coup joué et le meilleur coup) et le prompt prêt à copier pour une IA.

Les maquettes de référence sont les écrans « Plateau de jeu », « Leçon et aide » et « Fin de partie » du canevas ci-dessus.

Alternatives écartées

• Conseil avant le coup, avec la réponse : le joueur n'essaie plus par lui-même, et on n'apprend pas en recopiant.
• Indice avant le coup, sans la réponse, en plus du commentaire après : écarté pour l'instant au profit d'un seul mécanisme simple. L'« indice » de la liste des fonctions du cadrage reste à concevoir séparément.

Conséquences

• Le commentaire après le coup demande une analyse du coup joué par le moteur (classement des coups et écart avec le meilleur). Elle doit tenir dans le budget de temps du téléphone, en arrière-plan, sans retarder le tour suivant.
• Les seuils entre « bon coup », « imprécision » et « erreur » sont à fixer, en s'appuyant sur ceux de GNU Backgammon (doubtful, bad, very bad).
• Les phrases du maître doivent rester exactes : elles s'appuient sur les coups et les chiffres du moteur, jamais sur une explication inventée.
• Les leçons sont des contenus sous CC BY-SA 4.0, à écrire et à faire relire par un joueur fort (cadrage, risque « contenus longs à produire ») ; leur progression est stockée localement.

Amendements

2026-11-12 — Les cinq premières leçons, sans relecture préalable

Décision de Pierre du 2026-11-09 (docs/etape-1.md, « Décisions de Pierre ») : les leçons ne sont pas relues par un joueur fort avant d'être livrées ; elles le sont telles quelles et améliorées sur retours d'experts. La relecture prévue ci-dessus est remplacée par des garde-fous vérifiés par make test (app/tests/lessons.test.ts) :

• chaque exercice « à vous » attend un seul coup, le meilleur coup du moteur à 2 plis, avec plus de 0,04 d'équité d'avance sur le deuxième ; il accepte ce coup et refuse tous les autres ;
• chaque coup illustré est aussi le meilleur coup du moteur à 2 plis ;
• chaque compte de points cité par le texte est celui du moteur ;
• le texte n'affirme rien que le moteur ne confirme : les coups, les points faits, les pions frappés ou laissés seuls, lisibles dans la position ; aucune explication stratégique inventée.

Les cinq leçons (étape 1g) vivent dans docs/lecons/ (format et garde-fous : docs/lecons/README.md), au format du tutoriel, et réutilisent son écran. L'état d'une leçon est « à commencer », « 2 exercices sur 4 » ou « terminée » (tous ses exercices réussis) ; toutes restent ouvertes, l'ordre est conseillé. La progression est enregistrée avec les parties (ADR 0007, amendement du 2026-11-12) ; leurs adresses sont dans l'ADR 0013 (amendement du 2026-11-12).