Compétence Mentale (Mental)

Mental

Expliquez le système à travers ses acteurs, ses limites et ses communications.

Contrat de sortie : diagramme d'abord

Une explication mentale complète DOIT inclure un diagramme dans la réponse elle-même. Écrivez une courte phrase pour orienter le lecteur, puis incluez immédiatement :

• Un bloc mermaid délimité utilisant sequenceDiagram et autonumber (par défaut).
• Une image D2 rendue et intégrée, si le rendu est disponible et que D2 est demandé.

Ensuite, expliquez le flux et son évolution dans une prose concise. Construisez le diagramme avant d'écrire l'explication plus longue, afin que le visuel ne puisse pas être abandonné à la fin. Ce contrat s'applique également aux réponses courtes et aux explications de suivi qui poursuivent une discussion de modèle mental explicitement invoquée. Une question de clarification seule n'a pas besoin de diagramme. Si l'utilisateur demande explicitement de ne pas avoir de diagramme, suivez cette demande.

Les flèches ASCII, les listes à puces, les tableaux, les blocs de code ordinaires, un lien vers un diagramme, une promesse d'en dessiner un plus tard, et le code source D2 non rendu ne satisfont pas ce contrat. Ne demandez pas si l'utilisateur veut un diagramme. Si aucun moteur de rendu n'est disponible, émettez quand même le code source Mermaid ; ne le remplacez pas par du texte car la discussion pourrait ne pas le rendre. Aucun outil de génération de diagramme n'est nécessaire pour un bloc de code Mermaid.

Exemple de la forme de réponse requise (adaptez les acteurs au contexte réel) :

Le navigateur demande à l'API de sauvegarder des données ; l'API possède l'accès à la base de données.

```mermaid
sequenceDiagram
    autonumber
    participant Navigateur
    participant API
    participant BaseDeDonnées
    Navigateur->>API: Sauvegarder les données du formulaire
    API->>BaseDeDonnées: Stocker les données acceptées
    BaseDeDonnées-->>API: Enregistrement sauvegardé
    API-->>Navigateur: Réponse de succès
```

Le formulaire commence dans le navigateur. L'ajout d'une API permet de sauvegarder à distance ;
l'ajout d'une base de données permet aux données sauvegardées de survivre à une requête individuelle.

Invocation explicite

Utilisez cette compétence uniquement lorsque l'utilisateur la demande explicitement : /mental, $mental, ou une demande directe d'utiliser la compétence mentale. Une demande générale d'explication n'active pas cette compétence. Traitez cela comme une demande d'explication, pas une autorisation pour implémenter, installer, publier ou modifier le système expliqué.

Utilisez le sujet qui suit l'invocation, ou déduisez-le de la conversation. Posez une seule question ciblée uniquement si le sujet ne peut pas être raisonnablement déduit.

Construire l'explication

1. Ancrez le modèle dans la conversation et les preuves disponibles. Pour un code source existant, inspectez uniquement les points d'entrée ou la configuration nécessaire pour établir les relations pertinentes. Distinguez les faits observés des hypothèses. N'inventez pas de services, de déploiements réussis ou de comportements vérifiés.
2. Commencez par le plus petit système utile : un script fonctionnant localement, un navigateur affichant une page, ou un service répondant à une requête. Expliquez ce qui fonctionne déjà avant d'introduire l'infrastructure.
3. Progressez vers le système discuté. À chaque étape significative, expliquez le nouveau besoin, l'acteur ou la connexion ajouté pour y répondre, et comment une action traverse désormais le système. Ce sont des étapes explicatives, pas des affirmations sur la chronologie historique. Si l'utilisateur pose des questions sur l'évolution réelle du projet, utilisez l'historique disponible et identifiez les lacunes.
4. Choisissez les acteurs en fonction du contexte : personnes, processus, services, stockage, registres, files d'attente ou fournisseurs externes. Donnez à chacun un rôle concret. Regroupez les acteurs liés par machine, processus ou limite réseau lorsque l'emplacement affecte la compréhension.
5. Tracez une action concrète à travers les acteurs dans l'ordre, y compris le résultat revenant à l'appelant. Étiquetez ce qui traverse chaque limite : code source, archive de paquet, requête HTTP, réponse JSON, événement ou donnée stockée. Séparez la configuration et la distribution de la communication au moment de l'exécution lorsque les deux sont importants.
6. Expliquez les distinctions uniquement là où elles résolvent une confusion. Par exemple, un nom de paquet choisit quoi récupérer, un nom de commande choisit quoi exécuter, et un argument devient une entrée pour cette commande. Pour un exemple navigateur/API, distinguez la livraison du code des requêtes API ultérieures.

Préférez une progression courte avec une prose connectée plutôt qu'un glossaire ou un catalogue de composants. Si l'utilisateur ne veut que l'interaction actuelle, montrez ce flux sans forcer une longue évolution. Les commandes et extraits doivent ancrer le modèle ; évitez les inventaires de drapeaux, les procédures d'implémentation et les alternatives non liées. Conservez les détails qui modifient le modèle, comme un cache évitant un téléchargement ou un accusé de réception asynchrone arrivant avant la fin du travail.

Précision du diagramme

Chaque réponse produite avec cette compétence doit contenir au moins un diagramme Mermaid ou une image D2 rendue. Par défaut, utilisez un bloc mermaid délimité : il ne nécessite aucun outil de rendu et le source reste lisible lorsque le rendu n'est pas disponible.

• Préférez un diagramme de séquence numéroté : commencez les diagrammes Mermaid par sequenceDiagram suivi de autonumber. Rendez l'ordre des appels, messages et réponses visible. Présentez les participants dans un ordre lisible de gauche à droite.
• Numérotez les réponses ainsi que les requêtes pour que le lecteur puisse suivre l'interaction complète. Tracez les étapes numérotées dans la prose ; gardez les références cohérentes avec le diagramme. La numérotation montre le scénario illustré, pas une affirmation que le travail concurrent se déroule toujours dans un ordre fixe. Utilisez par, alt, ou opt lorsque la concurrence, les alternatives, ou les étapes optionnelles modifient le modèle.
• Pour une évolution, utilisez des séquences numérotées petites et séparées pour les étapes significatives ; gardez les noms des participants stables et expliquez quel acteur ou message a été ajouté.
• Utilisez un organigramme uniquement lorsque la topologie ou la structure est la question principale et qu'une séquence l'obscurcirait, ou lorsque l'utilisateur en demande un. Pour les images D2 qui montrent une interaction, préférez une mise en page de séquence et numérotez explicitement les messages.
• Utilisez des noms d'acteurs concrets et des flèches directionnelles étiquetées avec des actions ou des données. Évitez les flèches non étiquetées et les boîtes décoratives qui n'expliquent rien.
• Gardez chaque diagramme centré sur l'interaction expliquée. Divisez les différentes phases ou les systèmes encombrés en petits diagrammes. Dans les diagrammes par étapes, marquez les acteurs et connexions nouvellement introduits.
• Gardez les étiquettes simples et mettez entre guillemets les étiquettes d'organigramme contenant de la ponctuation. Vérifiez les références de nœuds, la direction des flèches, les sous-graphes et la syntaxe délimitée avant d'envoyer.
• Un registre de paquets distribue du code ; ne le dessinez pas comme exécutant la CLI de l'utilisateur. Une base de données stocke des données ; ne la dessinez pas comme initiant des requêtes d'application ordinaires à moins que ce ne soit une fonctionnalité réelle du système.
• Si l'utilisateur préfère D2 et qu'un moteur de rendu est disponible, rendez et inspectez le résultat, puis intégrez l'image. Le code source D2 seul ne satisfait pas l'exigence d'image. Si le rendu n'est pas disponible, utilisez Mermaid et mentionnez brièvement la solution de repli. N'installez pas un moteur de rendu uniquement pour expliquer le modèle.

Suivez le diagramme d'une brève description de l'action concrète. Terminez lorsque le modèle est clair ; n'ajoutez pas de tâches d'implémentation ou de résumés génériques.

Avant d'envoyer

Inspectez la réponse elle-même : contient-elle un bloc mermaid délimité ou une image D2 rendue intégrée ? Si aucun des deux n'est présent, l'explication est incomplète. Ajoutez le diagramme avant d'envoyer. Pour un diagramme de séquence Mermaid, vérifiez que autonumber est présent. Vérifiez que ses flèches correspondent à la prose et tracent au moins une interaction réelle avec des acteurs concrets et une communication étiquetée.

Exemples

Consultez references/examples.md lorsque des exemples pourraient aider à calibrer l'explication. Il inclut la distribution npm, les appels frontend/backend, les appels service à service et les travaux asynchrones. Adaptez l'approche au contexte réel plutôt que d'importer ces acteurs dans chaque explication.