jasonericsiegel/feedback-humain

Feedback Humain

Transforme toute page HTML en une page que l'utilisateur peut commenter : un plan à gauche, ses notes à droite à côté de ce qu'il lit, et un bouton Copier : Copier mon feedback quand c'est vide, Copier N notes avant sa première copie, puis Copier N nouvelles notes ou Copier à nouveau. L'utilisateur colle le texte copié dans le chat ; vous l'appliquez. Chaque frappe est sauvegardée dans son navigateur.

Cette version n'envoie pas de compteurs d'utilisation.

• Claude Code et Codex peuvent tous deux charger ce fichier. allowed-tools est un champ Claude Code ; Codex l'ignore.
• $SKILL_DIR désigne le dossier depuis lequel ce SKILL.md a été chargé (par exemple ~/.claude/skills/feedback-humain ou ~/.codex/skills/feedback-humain) ; écrivez ce chemin littéral dans les commandes. Chaque appel shell est un shell frais.
• Dans un sandbox Codex, add_notes.py ouvre la page via show.py, qui pilote Chrome via AppleScript et peut nécessiter une approbation : demandez-la plutôt que de sauter l'étape 3.
• Ce que leur page fait à chaque étape (votre curseur, l'ouverture de chaque tour, Reçu et Terminé) se trouve dans references/ce-que-lutilisateur-voit.md : lisez-le quand l'utilisateur demande comment la page se comporte.

Quand l'utiliser

• Vous demandez à l'utilisateur de réviser, approuver ou choisir parmi un travail que vous avez produit (un rapport, un plan, un brouillon, une maquette, des options, des règles proposées), ou il demande à le réviser → mettez-le sur une page ici, sans qu'on vous le demande.
• Le travail n'est pas encore une page → construisez du HTML simple à partir de celui-ci et conservez le fichier original comme source.
• Une question indépendante qui n'a pas besoin de page de révision reste dans le chat.
• Répondez aux questions de l'utilisateur dans les notes. Utilisez --reply sur la note qui pose la question, même si elle demande aussi une modification. Mettez les modifications, les explications plus longues et vos propres questions de révision dans la partie concernée de la page. Utilisez --ask ou --again pour une bulle avec votre propre question uniquement lorsque l'utilisateur en demande une.
• Une fois qu'une page est prête pour ses notes, et à chaque tour ultérieur : si inbox-for-human est dans votre liste de compétences disponibles (son nom, avec ou sans préfixe de plugin), chargez-la avec l'outil Compétence (dans Codex, ouvrez le SKILL.md pointé par sa liste de compétences) et mettez la page en file d'attente. Si ce n'est pas le cas, dites une fois : "Exécuté sans la compétence inbox-for-human, qui garderait cette page sur une liste de révisions."

Première utilisation

Avant la première page dans une configuration, exécutez python3 "$SKILL_DIR/scripts/self_check.py" et transmettez son message en termes simples. Ne le réexécutez pas après qu'il a réussi ; le script se souvient d'une vérification réussie. --force le réexécute si nécessaire.

Si vous ne pouvez pas exécuter de commandes ici du tout, n'essayez pas. Dites exactement : "feedback-humain ne peut pas fonctionner dans ce mode car je ne peux pas travailler avec des fichiers sur votre ordinateur ici. Dans l'application de bureau Claude, ouvrez l'onglet Code et choisissez une session Locale. Dans l'application de bureau ChatGPT, passez à Codex et restez sur Local."

La sortie 2, ou ce message, signifie arrêtez : n'essayez pas de construire une page. La sortie 1 donne un fichier que l'utilisateur peut ouvrir lui-même pour vérifier.

1. Marquer les parties

Mettez data-note sur chaque partie que l'utilisateur peut commenter comme une unité : une carte, une section, une option, une ligne de tableau. Les étiquettes proviennent du premier titre de la partie, donc un simple data-note suffit généralement. Une partie sans titre, ou dont le titre répète celui d'une autre partie, reçoit sa propre étiquette : data-note="Option B · Calme". Les étiquettes doivent être uniques sur la page.

Une page qui tire ses parties de son propre script reçoit également des notes dessus, tant que le script les dessine immédiatement, et non lors d'un événement ultérieur comme DOMContentLoaded ou un clic. Ne les copiez pas dans le HTML ; le décompte de l'étape 2 ne couvre que les parties écrites là.

Marquez la partie autour d'une page locale affichée dans une <iframe>. L'étape 2 étiquette la page encadrée afin que ses mots offrent Commentaire, Modifier et Surligner. La page de révision sauvegarde le feedback et nomme la source encadrée dans l'édition copiée.

Ne marquez jamais de texte à remplir ou réécrire par l'utilisateur, et ne demandez jamais à l'utilisateur de modifier la page : l'utilisateur réécrit lui-même toute ligne quand il le souhaite, avec Modifier dans la pop-up qu'un clic ou une sélection fait apparaître (⌘Z annule une modification). Posez plutôt des questions (étape 6).

Ne construisez pas de zones de commentaire, de champs de saisie ou de boutons de copie. La couche fait tout cela.

Le plan à gauche est déjà la navigation de la page : il liste chaque partie, montre les titres de section en dehors des parties comme légendes, marque la partie en vue, et saute à une partie dégagée de sa propre barre supérieure. Avant de donner à la page sa propre navigation (onglets de section, une liste de contenu, des liens de saut, un compteur d'étapes avec précédent et suivant), jugez ce qui est le plus simple pour l'utilisateur, afin qu'il ne rencontre jamais deux façons de faire une chose :

• Cela ne ferait que répéter le plan → laissez-le de côté. Nommez les parties et les titres de section comme ses boutons les auraient dits.
• Cela fait quelque chose que le plan ne peut pas faire (un interrupteur Clair/Sombre, un filtre, des boutons précédent et suivant qui défilent la page partie par partie) → gardez uniquement cette partie.
• Cela montre des parties dans des onglets ou autres panneaux cachés → faites-en une page à défilement unique. L'utilisateur a demandé des onglets → marquez-les et n'écrivez rien d'autre : une role="tablist" de <button role="tab" aria-controls="…">, chacun nommant un role="tabpanel", puis des parties data-note dans les panneaux comme d'habitude. La couche change les panneaux, dessine une barre collante simple, liste chaque onglet dans le plan comme un niveau de sa hiérarchie, là où il se trouve sur la page, conserve l'onglet ouvert entre les rechargements et les versions, ouvre un onglet pour une ligne de plan, un stepper ou un lien # vers lui, et maintient un fil jusqu'à ce que son onglet s'ouvre. Une page avec son propre script d'onglets le conserve, et une liste d'onglets avec une class conserve le style propre de la page.
• Chaque page reçoit des versions à partir de son deuxième tour (étape 5) → ne liez pas les touches ← et → ; le stepper de versions les utilise.

Points d'intégration, pour toute page qui héberge la couche (une page faite par une autre compétence, ou à la main) :

• Les parties data-note alimentent le Plan et la colonne de notes, comme ci-dessus.
• data-notes-layer est défini sur <html> une fois que la couche a dessiné, et est absent sur une page sans elle. Une page hôte l'utilise pour masquer son propre plan, ou une ligne qui n'a de sens que sans la couche, afin que l'utilisateur ne voie jamais deux choses : html[data-notes-layer] .son-plan { display: none; }. Rien n'éteint la couche, donc le marqueur reste. Ne vous fiez à rien d'autre ajouté par la couche.

2. Activer les notes

python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude"

Il ajoute une balise juste avant </body>, imprime le nombre de tours et de parties, et ouvre la page via show.py. Les réexécutions, --next-round et l'exécution de suivi d'une nouvelle version l'ouvrent aussi ; --new-version seul, --received et --converged ne le font pas. Si l'ouverture échoue, la page reste prête et l'exécution imprime pourquoi et la commande pour l'ouvrir à la main. Lors d'un premier tour, il met également un petit style dans l'en-tête de la page, qui la garde cachée jusqu'à ce que la couche la dessine. La réexécution remplace la balise, alors exécutez-la à nouveau après avoir réécrit la page. Un avertissement concernant l'absence de parties ou une étiquette en double → corrigez les marques et réexécutez.

• --hold : préparer la page sans l'ouvrir, pendant que vous la construisez ou la vérifiez, ou lorsque l'utilisateur demande uniquement un lien (étape 3).

• --pictures off : désactiver les pièces jointes pour une page partagée avec d'autres personnes ou une version publique ; les exécutions ultérieures conservent le réglage.

• --agent : votre nom tel que les gens le connaissent. Claude Code passe Claude, Codex passe Codex, tout autre agent son propre nom de produit. Un curseur portant ce nom et votre logo fait votre part sur leur page : il tape vos messages et clique dans les états de leur barre de notes (Reçu et Mise à jour à l'étape 4, Terminé à l'étape 8). Les exécutions ultérieures conservent le nom, alors passez-le la première fois.

• --helper "<nom>" et --owns "<nom>:[Étiquette de partie]" : un autre agent a fait des parties de la page (un sous-agent que vous avez envoyé, Codex, n'importe qui d'autre que vous). Nommez chaque aide une fois, comme les gens le connaissent, et chaque partie qu'il a faite avec --owns, l'étiquette telle que le Plan la montre ; les deux se répètent, trois aides au maximum. Vous restez le responsable (--agent). Sur la page, le curseur de chaque agent ne fait que ce qu'il possède. Les exécutions ultérieures les conservent ; une exécution avec l'un ou l'autre drapeau les remplace ; une nouvelle version commence sans eux, alors repassez-les lors de son exécution de suivi lorsque ses parties sont toujours les leurs. Vous avez tout fait → laissez les deux de côté.

  python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude" --helper "Codex" --owns "Codex:[Option B · Calme]"
  

• --workspace <répertoire> : votre espace de travail (le dossier du projet dans lequel vous travaillez). Chaque exécution crée <répertoire>/feedback-humain/attachments/ s'il manque, avec un fichier marqueur dans feedback-humain/ ; la page sauvegarde les images que l'utilisateur attache là, après que l'utilisateur a sélectionné ce dossier feedback-humain une fois dans Chrome, et les invites de la page vous nomment ("Dans le dossier de l'espace de travail de Claude, sélectionnez le sous-dossier feedback-humain…"). Sans cela : le dépôt de la page, sinon le dépôt de votre répertoire actuel, sinon le répertoire actuel. Les exécutions ultérieures conservent le dossier que la balise nomme.

• La page est servie via http (elle utilise fetch, des modules ou des ressources ../) → ajoutez --copy, qui place human-feedback.js à côté de la page. Les exécutions ultérieures, les réécritures et les nouvelles versions le conservent, et le disent.

• Ne collez ni n'incorporez jamais human-feedback.js dans la page, et ne le lisez jamais : la balise est tout ce dont la page a besoin.

• Mettez les questions sur la page dans la partie qu'elles concernent (étape 6).

Apparence

• Suivez l'apparence du système par défaut. Proposez Auto, Clair et Sombre lorsque le matériel en cours de révision est de la prose dans les styles de lecture partagés, ou lorsque l'utilisateur demande le contrôle. Laissez-le de côté sur les autres révisions.
• Lorsque vous proposez le contrôle, utilisez --appearance page si la colonne de lecture a déjà les deux palettes et que vous pouvez vérifier les deux. Réutilisez-les dans la même page. Pour une page avec un thème indépendant, sans palette testée, ou dont l'apparence fait partie de la révision, utilisez --appearance sidebars pour basculer le Plan et les Notes seuls. Conservez les captures d'écran et les intégrations telles quelles.
• Dans le CSS de la colonne de lecture, html[data-notes-layer="light"] et html[data-notes-layer="dark"] sont les choix explicites. Conservez la requête média système pour Auto et lorsque la page s'ouvre sans la couche. Le choix de l'utilisateur reste avec cette révision au fil des tours. Les autres révisions commencent en Auto.
• Une réexécution ou une version copiée par --new-version conserve le réglage. Passez --appearance off pour supprimer le contrôle, ou repassez le réglage prévu lors de la reconstruction du fichier à partir de zéro.

3. L'afficher

Pour tout type de révision, à chaque tour :

• Une fois la révision prête, ouvrez-la dans le navigateur de l'utilisateur à chaque tour. L'ouvreur réutilise l'onglet existant dans Chrome lorsqu'il trouve un tour précédent là. Utilisez --hold pendant la construction ou la vérification de la page, ou lorsque l'utilisateur demande explicitement uniquement un lien.
• Pour une révision locale, terminez avec add_notes.py sans --hold. Les nouvelles révisions dans un dossier dédié dont les ressources vivent dans ce dossier utilisent une seule adresse web locale pour tous les tours, afin que le navigateur conserve le zoom de la page et les notes. Conservez les tours et leurs ressources dans ce dossier ou ses sous-dossiers et utilisez des chemins de ressources relatifs. Liez l'adresse de révision que l'ouvreur imprime.
• Pour une page déjà servie via HTTP, préparez avec --hold --copy et exécutez show.py <page locale.html> --preview-url <URL HTTP du nouveau tour>. Conservez le même serveur de prévisualisation entre les tours afin que l'ouvreur puisse trouver l'onglet existant et que le navigateur conserve les notes de l'utilisateur.
• Mettez le lien de la page dans votre réponse à chaque tour. Utilisez le format de lien de votre projet, avec le résultat de l'ouvreur pour indiquer où se trouve la page. Si l'ouvreur échoue ou dit qu'il a laissé la page fermée, dites-le et donnez le lien.
• Une page dont les tours ou versions précédents ont été ouverts par l'utilisateur depuis file:// → continuez à la montrer depuis file:// (show.py sur son chemin) et ne donnez pas de lien localhost, même là où le projet en demande un : le navigateur conserve les réponses de l'utilisateur par adresse, donc une copie localhost n'en montre aucune et rouvre les fils qu'ils ont fermés. Dites dans la réponse pourquoi il n'y a pas de lien.

Ne faites cela qu'une fois la page prête pour leurs notes.

Exécutez add_notes.py sans --hold une fois la page prête pour leurs notes. Terminez d'abord le contenu de la page et marquez chaque partie. Passez toutes les marques terminées et toutes les bulles demandées par l'utilisateur dans cette exécution (l'exécution de suivi de l'étape 5 pour une nouvelle version).

Un correctif que vous avez dit à l'utilisateur qu'il arrive tient aussi la version suivante. Montrez-le une fois que ce correctif est en direct.

Pour une vérification, préparez-la avec --hold, puis vérifiez-la vous-même (ou faites-la capturer par un sous-agent) avec la couche de notes activée, car la couche rétrécit la page, et corrigez ce que vous trouvez. Vos messages (questions, réponses) n'arrivent que lorsque l'onglet a le focus, et un navigateur sans tête ne le focalise jamais à moins que l'émulation de focus ne soit activée (tests/harness.mjs l'active). Sans cela, vérifiez les messages dans les données de la balise à la place, et la page elle-même reste vierge derrière son ouverture : capturez-la avec shoot_page.py de reading-page-formats, qui capture puis supprime une copie nue sans la balise et son style de maintien. Cette copie nue remplit toute la fenêtre, mais sur leur écran les colonnes de notes prennent environ 375px de chaque côté (mesuré à 2560 de large, 2026-11-01). Capturez-la donc aussi à cette largeur plus étroite, et corrigez tout enroulement ou débordement avant de la montrer. Une copie nue ne peut pas montrer les colonnes couvrant la page, alors chargez aussi la page maintenue avec la couche activée et vérifiez que document.querySelector('h1').getBoundingClientRect().left est à droite du bord du plan ; le premier élément de texte fera l'affaire sur une page sans h1. Ce n'est qu'alors qu'il faut ouvrir la page en utilisant la commande locale ou HTTP ci-dessus. Dites à l'utilisateur qu'elle est prête pour ses notes, où elle se trouve (la ligne que l'ouvreur imprime), et de coller ce que Copie lui donne. Si vous avez posé des questions ou laissé des réponses, dites combien attendent dans la page.

Une fois qu'une page est affichée, gardez le chat sur la ligne de prêt, le lien, et tout ce qui a empêché la page de s'ouvrir ou une ligne requise par une autre compétence. Mettez les modifications, les résultats, les sources, les mises en garde, les vérifications et les questions dans les parties qu'ils concernent. Utilisez les propres Plus d'infos de la page pour les sources et les détails quand elle en a une.

Une page que vous avez encadrée porte aussi la balise d'encadrement, donc ouverte seule elle montre les colonnes de notes et se rétrécit, et une vérification signale de faux défauts. Vérifiez-la à partir d'une copie nue dans votre bloc-notes à la place : supprimez le style de maintien, supprimez la balise du script, puis ouvrez cette copie nue dans un navigateur, ou avec la capture d'écran à la fois en pleine largeur et à 1920px de large. Ne montrez jamais la copie nue, ne l'utilisez que pour vérifier. Une copie nue ne peut pas montrer les colonnes couvrant la page, donc chargez aussi la page maintenue avec la couche activée et

[suite tronquée — la traduction complète suit le même principe]