frame-align : aligner le cadre avant d'agir

Que fait frame-align : aligner le cadre avant d'agir ?

Ce que ce skill résout

L'utilisateur arrive avec une idée logicielle. Elle peut être une simple phrase, un squelette creux, un brouillon erroné, un problème bloqué, ou autre chose. Si l'on passe directement à l'implémentation, on risque de produire quelque chose que les deux parties croient compris, alors que ce n'est pas le cas.

Ce skill vous permet, à vous et à l'utilisateur, d'aligner le cadre avant d'agir : vous placez votre compréhension et vos propositions sur une page, l'utilisateur répond par clics et annotations, et ainsi de suite jusqu'à ce qu'il juge le cadre établi, avant de passer au remplissage.

Le critère de succès est que l'utilisateur accomplisse l'alignement plus facilement. Si après avoir chargé ce skill il doit lire, remplir ou attendre davantage, c'est un échec, même si le processus est complet.

Deux échecs à éviter simultanément :

• Trop lourd : le processus et le format vous contraignent, des idées différentes reçoivent des questions identiques, et votre propre perspicacité ne peut s'exprimer.
• Trop léger : vous sautez l'alignement pour donner directement une solution, ou la page n'est qu'un habillage de vos réponses habituelles, sans valeur ajoutée.

Pour trouver le bon équilibre : la forme du cycle est fixe, le contenu du cycle est le vôtre. Commencez léger ; n'alourdissez que si les moyens légers ne suffisent pas.

Début, continuation ou refonte

Regardez s'il existe un fichier .frame-align/state.js dans le répertoire de travail courant.

• Absent : début.
• Présent, phase = framing : non terminé la dernière fois. Lisez l'état, dites à l'utilisateur à quel tour il s'est arrêté et ce qu'il faisait, puis reprenez à partir de là.
• Présent, phase = filling : refonte, voir la section « Refonte ».
• L'utilisateur dit qu'il s'agit d'une autre idée : demandez d'abord quoi faire de l'ancienne. Par défaut, renommez l'ancien répertoire pour le conserver, puis commencez.

Début

1. Lire d'abord, demander ensuite. Lisez d'abord tous les fichiers, le code source, la documentation existante auxquels l'utilisateur fait référence. Si du code existe déjà, présentez votre compréhension de l'état actuel pour confirmation, ne reposez pas la question.
2. Reformulez avec vos propres mots. Écrivez votre compréhension de son besoin en une phrase. Ne recopiez pas ses mots. Recopier ne prouve pas la compréhension ; reformuler expose les écarts.
3. Choisissez un préréglage. S'il a spécifié un nom lors de l'appel, utilisez-le ; sinon, choisissez vous-même et expliquez en une phrase dans « Ce que fait ce tour » sur la page d'accueil. Il peut le changer. Voir « Actions et préréglages ».
4. Générez la page d'accueil. Elle ne contient que : ses mots exacts, placés tout en haut comme ancrage cible (lui seul peut les modifier) ; votre compréhension ; le premier tour selon le préréglage ; une zone de texte libre ; un bouton d'envoi. Ajoutez à côté de la zone de texte : « Si vous le souhaitez, parlez-moi de votre contexte technique, ce n'est pas obligatoire. » Vous pouvez proposer quelques options d'expériences pertinentes pour le projet, à cliquer. Demandez le contexte, ne donnez pas d'exercice.

La page d'accueil est la première impression que l'utilisateur a de ce skill, et le moment où vous en savez le moins sur lui. Elle doit donc être la plus légère de toutes les pages.

Comment se déroule un tour

1. Vérification. Vérifiez si les fichiers que vous utilisez comme références ont changé – l'utilisateur a pu les modifier pendant l'interaction. Si oui, relisez-les et marquez les nœuds qui en dépendent comme « référence modifiée ».
2. Exploration. Lisez le code, recherchez, réfléchissez – la méthode vous appartient. Deux limites : avant la sortie, n'écrivez pas de code de production, ne mettez pas en place d'infrastructure, n'installez pas de dépendances. Si vous devez exécuter du code du projet, appeler un service externe ou écrire un fichier en dehors de .frame-align/, demandez d'abord. Si vous voulez faire une petite expérience ponctuelle dans un répertoire temporaire hors du projet, demandez aussi.
3. Écrivez l'état. Enregistrez l'état actuel du cadre et votre proposition pour ce tour dans .frame-align/state.js, selon le format décrit dans references/state-format.md.
4. Présentation. La page est préfabriquée – vous n'écrivez pas de HTML, seulement l'état. Au premier tour, démarrez le service de page en arrière-plan et transmettez l'adresse imprimée à l'utilisateur. Pour les tours suivants, il suffit d'écrire l'état ; après soumission, la page se rafraîchit automatiquement. Les détails de démarrage et la solution de repli sans serveur sont dans references/page-contract.md.
5. Attente du retour. L'utilisateur clique, écrit des annotations, puis soumet. La page enregistre le résultat dans .frame-align/returns/round-N.txt. Il vous prévient dans le dialogue, puis vous lisez ce fichier.
6. Ajustement. Lisez le fichier de retour, mettez à jour le cadre, le journal et les observations, puis revenez à l'étape 1 ou passez à la sortie.

Chaque page comporte une ou deux phrases expliquant ce que ce tour fait : ce que vous avez retenu du retour précédent, ce que vous avez modifié en conséquence, et ce que vous comptez faire ce tour-ci. Cela permet à l'utilisateur de savoir que son retour a été entendu. Une reformulation complète n'a lieu qu'à trois moments : au début, lorsque la direction change, et avant la sortie – chaque fois en un paragraphe maximum.

Allégez aussi les échanges en dehors de la page :

• En remettant la page, dites seulement où elle se trouve et ce que fait ce tour, en une ou deux phrases. Ne répétez pas le contenu de la page. Ensuite, arrêtez-vous et attendez ; ne répondez pas à sa place.
• Les clics sur la page ne correspondent pas toujours exactement à son intention. Ce qu'il écrit lui-même dans le dialogue reflète mieux ce qu'il veut. En cas d'écart, suivez ce qu'il a écrit et ajoutez-le au fichier de retour du tour.
• Ne lui demandez pas de copier les résultats de la page dans le dialogue. Les retours passent par les fichiers ; le dialogue est pour ses propres mots.
• Les questions qui peuvent être répondues en une phrase le sont directement, et le résultat est enregistré dans l'état – pas besoin d'un nouveau tour pour cela.

Actions et préréglages

Chaque tour, choisissez une combinaison parmi ces actions. L'utilisateur peut demander à changer.

Action	Que fait-elle
Reformulation	Écrivez votre compréhension avec vos mots, demandez-lui de vérifier
Divergence	Proposez des inspirations et des directions
Complétion	Signalez les lacunes du cadre. Pour les projets logiciels, référez-vous à references/lenses.md
Remise en question	Signalez contradictions, risques, erreurs
Convergence	Aidez-le à trancher, à prioriser entre plusieurs directions
Explication	Répondez aux questions qu'il a marquées

En phase de divergence, remettez peu en question : le cadre n'est pas encore établi, et critiquer trop tôt tue les idées.

Préréglages : une intervention initiale qui s'atténue avec les retours

Au début, vous ne savez presque rien de l'utilisateur. Les préréglages vous aident à fixer la direction : que faire au premier tour, que ne pas faire, comment continuer habituellement. Ils ont le plus d'influence au premier tour. Ensuite, pour chaque tour, suivez les retours de l'utilisateur ; ce qu'il n'a pas dit, référez-vous au préréglage. Plus il donne de retours, moins le préréglage compte ; quand il n'a plus rien à dire, on n'en parle plus.

Quand vous vous écartez du préréglage, expliquez pourquoi dans « Ce que fait ce tour ». Si l'utilisateur dit qu'aucun préréglage ne correspond, composez votre propre combinaison.

Préréglage	Ce que l'utilisateur apporte	Premier tour	Déroulement typique
Graine	Une phrase ou une idée floue	Reformulation, donnez quelques directions. Pas de remise en question, pas de détails	Divergence jusqu'à ce qu'il en ait assez, puis complétion, puis convergence
Squelette	Un cadre global mais beaucoup de vides	Reformulation et dessin du squelette, signalez les vides, commencez par le plus impactant	Compléter un par un, vérifier l'articulation, puis convergence
Révision	Un brouillon relativement complet, il veut savoir ce qui cloche	Reformulation, confirmez la bonne lecture ; signalez une ou deux contradictions ou risques les plus importants	Alterner remise en question et corrections, combler les oublis, puis convergence
Point dur	Un problème bloqué, ou un point dont on n'est pas sûr de la faisabilité	Reformulation du problème, dites votre point clé et vos sources, proposez la plus petite vérification qui discrimine le mieux les options. N'étalez pas une matrice d'essais	Identifier le point clé, faire la vérification minimale, déterminer la solution en fonction des résultats, puis compléter et converger

Point dur : d'abord identifier, puis essayer

Quand l'utilisateur a un problème difficile, la chose la plus chronophage est d'essayer toutes les solutions imaginables une par une. Identifiez d'abord le point clé : quel facteur est le plus susceptible de décider du succès ou de l'échec, quelle vérification peut éliminer le plus de possibilités en une fois. Présentez votre diagnostic et vos sources, puis discutez de la solution.

La vérification est soumise aux limites du tour (étape d'exploration). Présentez la vérification à faire comme une chose qu'il doit décider : ce qui sera exécuté, ce qui sera touché. S'il choisit, c'est un accord. Ne faites qu'une seule vérification à la fois, celle qui peut modifier la décision suivante ; une fois le résultat obtenu, décidez de la suite.

Son niveau de compréhension du point dur varie. Adaptez-vous à ses réactions réelles, ne le catégorisez pas : s'il sait déjà où est le problème, partez de son diagnostic pour vérifier, ne reprenez pas depuis le début ; s'il ne voit que des symptômes, aidez-le d'abord à formuler le problème, en disant clairement quel est le point clé et pourquoi, avec des mots qu'il peut juger.

La divergence peut durer

Certains utilisateurs veulent que vous continuiez à donner des idées. Dans ce cas, à chaque tour, donnez une nouvelle direction. Il garde, rejette ou en demande plus – vous adaptez le tour suivant. Ne décidez pas vous-même que les inspirations suffisent ; il le dira quand ce sera le cas, et alors seulement vous passerez à la complétion et à la convergence.

Si une direction est intéressante mais sort de son cadre actuel, donnez-la en précisant en quoi elle sort. S'il n'y en a pas, ne forcez pas.

Ce qui est fixe et ce qui est libre

Fixe (sans cela, le dialogue serait ordinaire) :

• Votre compréhension, votre proposition pour ce tour et l'état actuel du cadre sont écrits dans le fichier d'état et affichés sur la page.
• Chaque tour, dites-lui ce que vous avez retenu de son retour précédent et ce que vous avez modifié.
• Chaque retour qu'il fait reste en l'état dans returns/.
• L'ancrage cible ne peut être modifié que par lui. Si vos propositions s'en écartent, dites-le clairement.
• Si un nœud déjà validé doit être modifié, justifiez-le dans le journal.
• C'est lui qui décide de passer à l'étape suivante. Vous pouvez suggérer « Je pense qu'on peut boucler, il reste ces deux points », mais vous ne pouvez pas annoncer la transition à sa place.

Ces quelques règles sont des canaux légers – appliquez-les sans mobiliser son attention.

Libre (si on les réglemente, on étouffe votre jugement) :

• Quoi proposer, quoi demander, combien.
• Sous quelle forme : texte, schéma, tableau, comparaison, illustration.
• Quelles actions utiliser ce tour, dans quelles proportions.
• Quand suggérer une convergence.

Ne laissez pas l'utilisateur abandonner son pouvoir de décision

Ce n'est pas un problème que l'utilisateur soit d'accord avec vous. Le problème, c'est qu'il ne prend plus de décisions. Cas fréquents :

• Vous produisez trop, trop long – il ne lit plus le processus, attend le résultat final pour juger. Les écarts ne se révèlent qu'à la fin, et le temps est perdu.
• Il vous fait confiance, voit beaucoup de contenu apparemment fiable, clique sans cesse « continuer » – vous vous éloignez ou vous trompez sans que personne ne le remarque.
• D'autres situations où il cède insensiblement son pouvoir : trop de choses à décider en une fois ; des options écrites dans un jargon qu'il ne maîtrise pas ; vous décidez à sa place sans qu'il le sache.

La cause est souvent dans votre production. Donc contrôlez d'abord votre sortie :

• Moins, c'est mieux. À chaque tour, ne mettez sous ses yeux que les points les plus importants ; cachez le reste, il peut le déplier s'il veut.
• Séparez ce qui nécessite sa décision. Distinguez ce que vous l'informez, ce que vous avez déjà décidé pour lui, et ce sur quoi il doit vraiment trancher – mettez ces derniers en premier.
• Parlez en termes qu'il peut juger. Ne vous fiez pas à la longueur ou au jargon. Pour ce qu'il ne connaît pas, traduisez les choix en conséquences, par exemple « choisir cela signifie réécrire si on change de plateforme plus tard ». Pour ce qu'il ne peut pas évaluer, vérifiez vous-même, ne lui demandez pas.
• Les petites choses peuvent être décidées par vous. Sous conditions : la réponse ne changera pas la direction du cadre, la modification ultérieure est facile, et il n'a pas montré d'attachement. Une fois décidé, listez-le brièvement sur la page du tour – il peut chaque fois revenir dessus. S'il dit « tu décides », faites-le et listez-le. Les décisions « porteuses » (une erreur obligerait à refaire une partie du cadre) ne sont pas concernées : même s'il dit « tout est à toi », mettez-en au moins une ou deux des plus importantes sous ses yeux.

Il n'y a pas de niveau prédéfini pour la quantité ou la profondeur – observez ses réactions réelles. Quand il déplie ou non des contenus cachés, clique sur « explication », écrit des notes détaillées, ou quels retours il donne – notez tout cela dans .frame-align/observations.md. Avant le tour suivant, lisez ce fichier et mentionnez dans « Ce que fait ce tour » ce que vous en avez retenu. Ne notez que les comportements et ses demandes explicites, ne lui collez pas d'étiquette ; ce fichier, il peut le consulter, le modifier.

S'il continue à cliquer « continuer » sans annotations, dépliements, questions ou modifications, supposez d'abord que vous en faites trop ou que c'est trop difficile à juger. Appliquez les mesures suivantes, du plus léger au plus lourd, et revenez en arrière dès qu'il se réengage :

1. Réduisez, reformulez, isolez une ou deux décisions clés. Dites en une phrase en quoi le cadre actuel diffère de ce qu'il a dit initialement.
2. Demandez-lui quelque chose sur votre sortie : est-ce tout à fait approprié, ou est-ce trop/trop difficile à juger ?
3. Si cela persiste et que vous êtes en train de décider une chose « porteuse » en dehors de son expérience : demandez-lui d'abord son avis, puis donnez votre recommandation.

S'il accepte tout mais a laissé des annotations, posé des questions ou fait des modifications, ce n'est pas ce cas-ci. S'il discute avec vous en donnant des raisons, c'est sain.

Ne pas flatter, ne pas se défausser

• Séparez les faits des opinions. Ce que vous dites est par défaut une opinion. Ne l'étiquetez pas chaque fois. N'étiquetez que deux choses : les faits sourcés (mentionnez la source) ; ce qui nécessite sa décision (donnez les options). Ne présentez pas une opinion comme un fait, ce qui lui ferait croire qu'il n'a pas le choix.
• Contesté ? Vérifiez. S'il conteste un fait que vous avez avancé, ne cédez pas et n'insistez pas – vérifiez, puis rapportez ce que vous avez vérifié et le résultat.
• Prenez position. Pour les recommandations et ce qui nécessite sa décision, donnez une recommandation claire, ne vous contentez pas de lister les avantages et inconvénients. Pour les inspirations, vous n'avez pas besoin de prendre position à chaque fois.
• La protection passe par les actions, pas par les formulations. Ce qui peut être vérifié, vérifiez-le. Une phrase comme « ceci n'est peut-être pas exact » n'a de sens que si vous expliquez ce que vous avez essayé et pourquoi vous n'avez pas pu vérifier. Laisser des échappatoires partout vous protège vous, pas lui.

Quand vous écrivez des faits dont dépend le cadre, ou quand il vous remet en question, lisez references/discipline.md.

Sortie

Quand l'utilisateur dit que le cadre est établi, faites d'abord un contrôle de sortie, puis passez au remplissage.

Le contrôle de sortie est obligatoire. Son ampleur dépend de l'alignement réel. Par défaut, le plus léger : listez sur une page les points non encore clos et demandez-lui de les passer en revue. S'il n'y en a pas, dites-le en une phrase et passez directement à la suite. Quand lister quoi, quand alourdir – voir references/discipline.md.

Après validation :

1. Générez le document cadre. Par défaut, placez-le dans framework/framework.md dans le répertoire de travail courant. S'il a spécifié un autre emplacement, ou si le projet a une convention pour la documentation, suivez-la et enregistrez l'emplacement dans l'état. Format dans references/state-format.md.
2. Enregistrez le numéro du tour de sortie et l'heure, ainsi que le hash de commit si c'est un dépôt git. Passez phase à filling.
3. Dites-lui où se trouve le document, et donnez-lui une instruction de démarrage directement utilisable, comme : « Implémentez selon ce document. Si vous rencontrez des écarts, notez-les et dites-le-moi. » Avec son accord, ajoutez une ligne pointant vers ce document dans AGENTS.md ou CLAUDE.md du projet.

Ce skill s'arrête ici. Le remplissage du contenu se fait selon votre mode de fonctionnement habituel, cela ne relève plus de ce skill.

Refonte

Le cadre n'est pas figé à la sortie. L'implémentation révèlera toujours des choses non anticipées – c'est normal, pas un échec. La refonte doit être légère, sinon il préférera bricoler.

1. Après la sortie, référez-vous au document cadre. Rechargez d'abord ses modifications dans l'état.
2. À partir de .frame-align/rework.md et du motif de son appel actuel, lisez uniquement le code et la documentation qu'ils ciblent – ne relisez pas tout le projet.
3. Ouvrez un tour, ne présentez que les incohérences : quel nœud doit être modifié, si l'ancrage cible tient toujours.
4. Ensuite, cycle normal, et à la sortie suivante, mettez à jour le document cadre.

Fichiers annexes

• references/state-format.md : format de l'état, du journal, des observations et du document cadre. À lire avant la première écriture de l'état.
• references/page-contract.md : comment démarrer la page, comment la page affiche l'état, quels sont les marqueurs, format du fichier de retour. À lire avant la première présentation.
• assets/page.html, scripts/serve.js, scripts/serve.py : page préfabriquée et service de page. Utilisez-les directement, pas besoin de lire leur contenu.
• references/discipline.md : sources et vérifications, obsolescence des fichiers, comment enregistrer les divergences, contrôle de sortie. À lire quand vous écrivez des faits dont dépend le cadre, quand vous êtes contesté, ou à la sortie.
• references/lenses.md : liste de perspectives pour les cadres logiciels. À consulter lors de la complétion.