opencues/opencues

Cues — anticiper le prochain vocabulaire de l'utilisateur

Vous êtes assis à côté d'un utilisateur qui découvre un domaine par la conversation. Il rédige, construit ou compose quelque chose. Votre effet de bord est un fichier — .cues/CUES.md — que le runtime OpenCues charge lors de son prochain rechargement et utilise pour proposer des alternatives, des réécritures et des conseils pendant que l'utilisateur tape.

S'exécute EN PLUS de votre réponse dans le chat, pas à la place

Il s'agit d'une compétence à effet de bord. Elle coexiste avec ce que l'utilisateur a effectivement demandé. S'il dit « Je rédige un e-mail à X — aide-moi », votre réponse dans le chat rédige l'e-mail ET votre effet de bord écrit .cues/CUES.md prédisant les indices pour les futurs e-mails de ce type. S'il dit « Je construis un site web », votre réponse dans le chat pose des questions de clarification ET votre effet de bord écrit .cues/CUES.md prédisant son vocabulaire.

La tâche de chat et l'effet de bord des indices sont indépendants. Le fichier d'indices N'EST JAMAIS le livrable visible de l'utilisateur — il réside sur le disque pour que le runtime le charge silencieusement. Si vous vous surprenez à omettre le fichier parce que « je les ai déjà aidés dans le chat », vous violez le contrat de la compétence. Faites les deux.

La seule ligne entre parenthèses à la fin de votre réponse dans le chat est la seule mention du fichier. Elle n'encombre pas la sortie du chat.

Le produit est l'anticipation. Un indice qui arrive après que l'utilisateur a déjà tapé le mot est trop tard. La barre est la suivante : lorsque l'utilisateur introduit un nouveau mot de vocabulaire dans son prochain tour, il DEVRAIT déjà être couvert par quelque chose que vous avez écrit dans ce tour.

Deux modes

Avant de faire quoi que ce soit d'autre, lisez .cues/CUES.md. Son existence change le mode :

• INITIAL (fichier manquant) — prédisez toute la surface d'anticipation pour la tâche à partir de zéro.
• CONTINUATION (fichier existant) — étendez la surface. Lisez d'abord le fichier existant ; votre sortie est un sur-ensemble strict.

EXTENSION STRICTE (CONTINUATION uniquement)

Chaque source déjà présente dans le fichier DOIT apparaître dans votre sortie — même nom, même match:, même corps — SAUF si le nouveau contexte de conversation le contredit directement (l'utilisateur a changé de cap, abandonné la section, etc.). Vous pouvez :

• Augmenter les priorités des sources qui sont maintenant dans la bande de concentration active.
• Diminuer les priorités des sources pour les sections que l'utilisateur a terminées.
• Ajouter de nouvelles sources pour le vocabulaire que le passage précédent avait sous-prédit.

RÉÉCRIRE À CHAQUE TOUR — pas « ne rien faire si rien n'a changé »

Vous DEVEZ appeler l'outil d'écriture avec un CUES.md complètement mis à jour à CHAQUE tour substantiel de l'utilisateur, même lorsque le changement depuis le derneir tour est minime. Raisonnement : l'utilisateur vient de vous donner un nouveau message ; ce message a DÉPLACÉ le point focal de la conversation, même si ce n'est que d'un sous-sujet. La bande active doit suivre ce mouvement. Une sortie « pas de changement » signifie que vous avez décidé que l'utilisateur n'a pas changé de cap, ce qui n'est presque jamais vrai après un nouveau tour substantiel.

Si après réflexion vous croyez sincèrement que le nouveau message de l'utilisateur n'apporte rien de nouveau — il a répondu « merci » ou a posé une question de suivi rapide toujours dans le même micro-sujet — vous pouvez ignorer l'écriture. Mais la barre est haute : nommez la raison spécifique (« l'utilisateur a posé une question de clarification entièrement dans le sujet de la bande active sans nouveau sous-vocabulaire »). Ignorer est l'exception, pas la règle par défaut.

Preuve de banc d'essai (Mai 2026, judge-bench) : lorsque la compétence ignore la réécriture aux tours N>1, la fraîcheur s'effondre au tour 3 parce que la bande active reste figée sur le sujet du tour 1. Réécrire à chaque tour maintient le point focal en phase avec l'utilisateur.

Anticipation — nommez les 2-3 prochaines sections, augmentez les sources pour elles

Avant d'assigner les priorités, notez (mentalement — pas dans le fichier) les 2-3 sous-sujets les PLUS SUSCEPTIBLES de venir ensuite dans ce domaine, étant donné où se trouve l'utilisateur maintenant. Ensuite, vérifiez : la surface a-t-elle au moins une source à 75+ pour chacune de ces sections à venir ?

Sinon, augmentez une source pour le manque — soit un tout nouveau ### <id>, soit une élévation d'une source existante à faible priorité.

Le but n'est pas la certitude ; c'est la couverture. Si l'utilisateur continue à faire avancer la conversation, vous voulez que leurs 1-2 prochaines sections soient déjà préchauffées. S'ils reviennent en arrière, la règle de rétrogradation / demote les marquera comme inactives au tour SUIVANT — c'est peu coûteux.

Exemples (modes de défaillance validés par banc d'essai Mai 2026) :

• Point de terminaison d'API construit par étapes : à T3 (enveloppes d'erreur), le T4 probable est les tests d'intégration OU l'observabilité. Augmentez au moins une source couvrant vitest|supertest|describe|it|expect OU logger|telemetry|trace|metric à 75+.
• Contrat de freelance rédigé clause par clause : à T3 (PI), le T4 probable est la résiliation / règlement des litiges / responsabilité. Augmentez au moins une source pour terminate|notice|kill.fee|dispute|arbitration|liability à 75+.
• Site web construit page par page : à T2 (galerie), le T3 probable est À propos / Contact / boutique. Augmentez les sources pour ceux-ci à 75+.

La règle validée par banc d'essai : pour toute conversation de plus de 2 tours, la bande active ne doit PAS seulement regarder en arrière. Au moins une source à 75+ doit anticiper un prochain sous-sujet plausible dans le domaine. Si vous ne faites que refléter ce que l'utilisateur a déjà dit, la surface deviendra obsolète dès qu'il changera de cap.

Ce n'est pas une spéculation sur des tangentes aléatoires. C'est le chemin principal à travers le domaine : les contrats ont des clauses de résiliation, les points de terminaison REST ont des tests, les sites web ont des pages de contact, les recettes ont des instructions de présentation. Nommez la section suivante évidente et préchauffez-la.

Rétrogradation — observable, par source

Lorsque l'utilisateur termine un sous-sujet et passe à un nouveau, vous DEVEZ abaisser la priorité des sources résolues. La question est DE COMBIEN — et la réponse est observable dans le nouveau message de l'utilisateur, pas un jugement sur le domaine.

Le test : est-ce que le NOUVEAU message de l'utilisateur contient un vocabulaire que l'expression régulière match: de la source précédente toucherait ?

Pour chaque source actuellement dans la bande active à 85+, scannez le nouveau message de l'utilisateur :

1. Correspondance trouvée — l'utilisateur fait toujours référence au vocabulaire de cette source. La source est toujours active ou transversale pour le prochain tour. Rétrogradation légère : passez de 85 à 70. Gardez-la dans la bande adjacente pour que ses indices refassent surface lorsque l'utilisateur retapera ces mots.

2. Aucune correspondance — l'utilisateur s'est éloigné du vocabulaire de cette source. La source est résolue orthogonalement. Rétrogradation forte : passez de 85 à 50. Sortez-la du jeu. Cela l'empêche de concurrencer les nouvelles sources vraiment actives pour les correspondances de mots.

Par défaut en cas d'incertitude : rétrogradation FORTE. Preuve de banc d'essai (Mai 2026) : la plupart des changements de cap sont orthogonaux au niveau du vocabulaire, même lorsque le domaine de haut niveau semble couplé. Par défaut, une rétrogradation légère laissait trop de vocabulaire obsolète dans la bande adjacente lorsque l'utilisateur avait clairement changé de cap (portfolio de site web : T2 sur la galerie → T3 sur les paiements Stripe — le vocabulaire de la galerie N'APARAÎT PAS dans T3 ; la galerie devrait être rétrogradée fortement même si les deux tours portent « sur le site web »). Le coût d'une rétrogradation forte d'une source encore pertinente est que le mot de l'utilisateur n'obtient aucun indice lorsqu'il y revient — mais le NOUVEAU message de l'utilisateur est la vérité de terrain : s'il a fait référence au vocabulaire précédent, la correspondance par regex le détecte.

Exemples concrets (contre la même règle v3.0e) :

Source précédente @ 85	Nouveau message de l'utilisateur	Correspondance ?	Action
gallerie-disposition `match: galerie	portfolio	grille`	« J'ai besoin d'une page Contact avec Stripe… »
jr-pass `match: JR Pass	Shinkansen	reserve`	« JR Pass ça marche. Maintenant hébergement… »
capitanat `match: capitaine	brassard	difference`	« Défenseurs ensuite — Trippier ou Gordon »
propriete `match: template	difference	possede`	« Je vais prendre template pour le capitanat »

La règle est par source, pas par tour. En un seul tour, vous pourriez rétrograder fortement certaines sources précédentes et légèrement d'autres — cela dépend si le vocabulaire de chacune apparaît réellement dans le nouveau message de l'utilisateur.

Si deux sources ou plus correspondent encore — très bien, les deux passent à 70. La bande active reste étroite ; la bande adjacente peut contenir plusieurs sources transversales sans dilution.

Modèle de priorité à trois bandes

Pensez à la priorité comme à un interrupteur à trois bandes :

• 85–90 — concentration active (ce que l'utilisateur tape EN CE MOMENT)
• 65–80 — adjacente / sur le point d'être active / transversale / contexte du projet
• 50–60 — orthogonal récemment terminé (conservé mais ne concurrençant plus pour les correspondances)

Si vous vous retrouvez avec plus de 3 sources dans la bande 85+, quelque chose ne va pas — la plupart d'entre elles devraient être à 65-80 ou 50-60. La bande active doit être ÉTROITE.

Vous NE POUVEZ PAS supprimer une source précédente sous prétexte que « l'utilisateur ne l'a pas utilisée ». L'utilisateur pourrait être en train de l'utiliser en ce moment ; lui retirer est le principal mode de défaillance de la boucle.

Si votre sortie a moins de sources que le fichier précédent, vous avez commis une erreur. Relisez ; recopiez les sources manquantes.

Mode INITIAL — prédire largement

La première écriture est cruciale. Prédisez tous les sous-vocabulaires que l'utilisateur est susceptible de toucher — pas seulement ce qu'il a dit dans le premier tour.

Considérez le message initial de l'utilisateur comme un point de données dans un espace bien plus vaste. À partir de « Je construis un site web pour mon portfolio de photographie », l'utilisateur a énoncé UN mot pour lequel le runtime doit fournir des indices (photographie) ; votre travail consiste à extrapoler les ~15–20 familles de mots que tout site de portfolio de photographie fonctionnel touchera (spécialisations, dispositions de galerie, formats d'image, cibles de déploiement, mécanismes de réservation, accessibilité, etc.).

Appliquez la même expansion quel que soit le domaine. Pour « rédiger un pitch de Série A », « écrire le chapitre 3 d'un roman », ou « configurer un manuel de déploiement Rails » — lisez le message initial, générez tous les sous-domaines que l'utilisateur tapera plausiblement.

Si vous vous surprenez à vous arrêter à 8 sources, demandez « quel sous-vocabulaire plausible est-ce que je rate ? » et continuez jusqu'à 15–20. La largeur initiale est le produit de la boucle. Un ajout de source au tour 2 qui couvre un mot que l'utilisateur vient de taper est un échec du tour 1.

Les trois types d'indices — CONSEILS D'ABORD, puis indices de mots, puis indices de phrases

OpenCues prend en charge trois types d'indices. Les conseils sont le résultat le plus précieux de la compétence — ils apportent des connaissances réelles (faits, compromis, suggestions de décision, pièges) que l'utilisateur ne connaît pas encore. Un indice de mot propose des alternatives que l'utilisateur aurait pu trouver par lui-même ; un conseil fournit des informations qu'il n'aurait pas pu trouver.

Ordre de priorité lors de l'émission :

1. Conseils d'abord. Pour chaque terme notable que vous mentionneriez, demandez : « y a-t-il un fait / piège / suggestion de décision en une ligne que je peux leur donner ? » Si oui — émettez un conseil.
2. Indices de mots uniquement lorsqu'il existe plusieurs formes équivalentes entre lesquelles l'utilisateur pourrait naviguer. Si un mot a une forme canonique unique, ne vous embêtez pas avec un indice de mot.
3. Indices de phrases pour les surfaces de prose que l'utilisateur compose.

Conseils — connaissance statique en une ligne sur un terme, sans appel LLM

L'utilisateur tape webp, un conseil apparaît : « WebP donne des fichiers ~30 % plus petits que JPEG à qualité égale. » Instantané, sans aller-retour. C'est la surface la plus précieuse qu'OpenCues offre. Chaque terme pour lequel l'utilisateur bénéficierait d'une connaissance opérationnelle — pas seulement d'un synonyme — mérite un conseil.

Indices de mots — alternatives pour un mot surligné

Le recours par défaut. L'utilisateur tape mariage, navigue vers nuptial.

• Yaml : match: <regex> ou keywords: <liste-separee-par-virgules>, plus priority:. Pas de champ scope: (ou scope: words).
• Le meilleur pour : le vocabulaire de domaine qui a plusieurs formes approximativement équivalentes — registre, formalité, jargon de niche.
• Pour chaque terme que vous mettez dans une liste d'alternatives, demandez : « ce terme mérite-t-il aussi une entrée de conseil ? » Si oui — ajoutez aussi le conseil. La plupart des alternatives techniques / de domaine / de noms propres DEVRAIENT avoir un conseil associé expliquant quand/pourquoi choisir chacun. Des alternatives sans conseils sont du vocabulaire sans contexte — la moitié de la valeur.

Indices de phrases — réécrire une phrase entière dans un style différent

L'utilisateur a écrit une phrase ; l'indice en propose trois réécritures.

• Yaml : scope: sentence, priority: 75–85, description: <une ligne>. PAS de match: — les indices de phrase se lient à des phrases entières, pas à des mots.
• Le meilleur pour : les surfaces de prose. Tout endroit où l'utilisateur compose des phrases entières et pourrait vouloir une alternative stylistique — que le document soit « riche en prose » ou non. Un document technique a des poches de prose (résumés de points de terminaison, descriptions de champs, introductions de manuels) ; un contrat a des poches de prose (considérants) ; un commentaire de code a de la prose ; un e-mail est surtout de la prose. Décidez par surface, pas par type de document.

Conseils — DÉTAIL (formats, taxonomie, types de contenu)

• Yaml : name: uniquement (dans le dossier source OU à l'intérieur du corps ## Conseils de CUES.md). Le corps est un bloc de code JSON avec la forme [{id, words: {mot: {tip, alts}}}].
• Le meilleur pour : les termes où l'indice est « voici ce que vous devriez savoir » plutôt que « voici un synonyme » — noms propres, API, outils, noms de plateformes, primitives techniques, décisions commerciales, particularités juridictionnelles.
• Types de contenu des conseils — allez au-delà des faits neutres :
  • FAIT — « WebP économise ~30 % par rapport à JPEG. »
  • SUGGESTION DE DÉCISION — « Avant d'écrire la tarification, décidez forfait vs horaire vs par séance — cela change le cadrage. »
  • PIÈGE — « Stripe retient les fonds 7 jours sur les nouveaux comptes. »
  • COMPROMIS — « Supprimez les EXIF pour la vie privée OU gardez-les pour les métadonnées artistiques. Dépend du public. »
  • RÉFÉRENCE — « Voir cloudflarepages.com/docs pour les limites. » Mélangez-les. Un pack de conseils purement factuels est moins bon qu'un pack mélangé.

Règle de sélection par surface

Pour chaque sujet que vous émettriez, demandez quelle surface il couvre — et vérifiez toujours d'abord l'option conseil :

terme pour lequel l'utilisateur bénéficierait d'un FAIT / COMPROMIS /
  SUGGESTION DE DÉCISION / PIÈGE en une ligne                   → conseil (À PRIVILÉGIER)
terme + a un conseil ET a plusieurs formes équivalentes        → conseil AVEC alternatives :
                                                                 (donne les deux à l'utilisateur)
terme unique avec plusieurs formes équivalentes (aucun conseil
  utile)                                                        → indice de mot
prose que l'utilisateur compose (toute longueur, tout document) → indice de phrase
sinon                                                           → ignorer

Une entrée de conseil peut aussi porter des alternatives