Communitygithub.com

work-brochure

Génère une brochure HTML visuelle autonome qui présente le travail terminé (schémas, captures avant/après, décisions, arborescence, extraits de diff, preuves de vérification), en complément du récapitulatif textuel dans le chat.

Qu'est-ce que work-brochure ?

Le skill **work-brochure** génère un résumé visuel complet du travail accompli sous forme d'une page HTML autonome. Il s'active automatiquement lorsqu'une pull request est ouverte, lorsqu'une fonctionnalité ou une correction est terminée, ou sur demande explicite de l'utilisateur (commande `/work-brochure` ou phrases comme « visuel récapitulatif », « résumé visuel », « guide-moi dans ce que tu as fait »). Le skill ne remplace jamais le récapitulatif textuel normal du chat ; il l'enrichit. La brochure inclut des diagrammes Mermaid (flowcharts, diagrammes de séquence, diagrammes d'état), des captures d'écran avant/après de l'application réelle, un arbre des fichiers modifiés, un tableau des décisions, des extraits de diff annotés et une section de vérification avec les résultats réels des tests. Tout le contenu est basé sur le diff réel, les commandes exécutées et l'application observée – aucune invention. La page est conçue pour être comprise en moins de deux minutes par une personne n'ayant pas participé à la session. Les visuels sont choisis en fonction de ce qui a changé (logique, UI, structure, nombres, état, etc.), avec au moins trois visuels pour un changement significatif. La brochure est sauvegardée localement (`.claude/work-briefs/`), affichée dans le panneau latéral et publiée comme Artifact privé pour persistance. Le skill fonctionne avec tout dépôt Git (GitHub PR ou plage de commits arbitraire).

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Brochure de travail

Après avoir terminé un travail, l'utilisateur souhaite deux choses :

  1. Le récapitulatif normal dans le chat, exactement comme vous l'écririez de toute façon (ce qui a changé, où ça en est, ce qui n'est pas fait). Ce skill ne le remplace jamais et ne le raccourcit pas.
  2. Une brochure : une page HTML autonome qui parcourt visuellement le même travail, afin que l'utilisateur puisse l'ouvrir à côté du chat et comprendre le changement à l'aide de diagrammes, de captures d'écran et de code annoté, plutôt que de longs paragraphes.

La brochure doit être fidèle au code. Chaque affirmation, nombre, chemin de fichier et capture d'écran provient du diff réel, des commandes que vous avez exécutées et de l'application que vous avez observée. N'inventez jamais un test qui n'a pas été exécuté ni un résultat que vous n'avez pas vu.

Étapes

1. Rédigez d'abord le récapitulatif du chat

Terminez le travail comme d'habitude, y compris votre résumé textuel normal et wrap_up (si l'application en possède un). Construisez ensuite la brochure. Si l'utilisateur a seulement demandé la brochure d'un travail antérieur, passez directement à l'étape 2.

Après l'ouverture d'une PR (le hook PostToolUse du plugin, ou celui de vos paramètres, ajoute un rappel après gh pr create), construisez la brochure pour cette PR avec gather.sh --pr <N> dans le même tour, et placez le lien de la brochure dans votre message de clôture. Ne modifiez pas le corps de la PR pour l'ajouter sauf si l'utilisateur le demande. Ignorez uniquement si la PR est triviale (une ligne, faute de frappe, version bump).

2. Rassemblez les faits

Exécutez l'outil depuis la racine du dépôt (il imprime les commits, un diffstat par fichier regroupé par dossier, les modifications non commitées et les infos de PR) :

bash <skill-dir>/scripts/gather.sh            # cette branche vs main + non commité
bash <skill-dir>/scripts/gather.sh A..B       # n'importe quelle plage git (ex. travail déjà fusionné)
bash <skill-dir>/scripts/gather.sh --pr 51    # une PR GitHub

Lisez ensuite les parties du diff qui comptent (git diff <range> -- <path>), pas la totalité. Collectez également à partir de cette conversation :

  • Pourquoi : le problème ou la demande dans les termes de l'utilisateur.
  • Décisions : les options que vous avez pesées et pourquoi vous avez choisi celle-ci.
  • Vérification : les commandes exécutées et leur sortie réelle, les captures d'écran prises, ce que vous avez vérifié dans le navigateur ou le simulateur, et ce que vous n'avez pas pu vérifier.
  • Points en suspens : les suivis, les risques, tout ce qui reste à faire.
  • Nécessite l'utilisateur : tout ce que seul l'utilisateur peut décider, vérifier visuellement ou approuver.

3. Capturez l'application réelle (lorsque le changement est visible)

Si le changement apparaît dans une interface utilisateur, la brochure doit montrer l'application réelle, pas une description.

  • Après : capturez d'écran de l'application en cours d'exécution sur le(s) écran(s) modifié(s) avec les outils de prévisualisation (preview_start avec le serveur launch.json du projet, naviguez, computer {action: "screenshot"}), ou le simulateur iOS screenshot. Capturez les largeurs desktop et téléphone si la disposition a changé.
  • Avant : si la différence est le point important, extrayez la révision de base dans un worktree temporaire dans le scratchpad (git worktree add <scratchpad>/before <base>), servez-le sur un port différent, capturez la même vue, puis supprimez le worktree (git worktree remove). Ignorez si le changement est purement additif ou si un "avant" n'apporte rien.
  • Enregistrez les captures d'écran sous forme de fichiers dans le scratchpad, réduisez-les (sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) et intégrez-les sous forme d'URI data:. Gardez la page entière sous ~8 Mo.
  • Pour les changements vidéo/animations, intégrez quelques images fixes (ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) ou une bande d'images, ainsi que les mesures chiffrées.
  • Les changements non visuels (scripts, données, backend) reçoivent des diagrammes et des sorties réelles plutôt que des captures d'écran.

4. Planifiez l'histoire, puis choisissez les visuels

Ordonnez la page comme l'utilisateur voudrait que cela lui soit expliqué : le résultat d'abord, puis comment ça marche, puis les détails. Choisissez les visuels en fonction de ce qui a changé. Préférez une image chaque fois qu'elle explique plus vite que du texte ; gardez la prose pour de courtes légendes et des paragraphes d'une à trois phrases.

Ce qui a changéVisuel à utiliser
Logique, pipeline, règle de décisionMermaid flowchart du nouveau flux ; mettez en surbrillance les nouveaux nœuds modifiés avec classDef changed
Requêtes entre parties (UI → API → stockage)Mermaid sequenceDiagram
Structure (modules, fichiers, forme des données)Arborescence de fichiers avec barres +/− ; Mermaid graph de la connexion des parties ; tableau des champs avant/après
UIPaire de captures avant/après ; annotez avec des appels numérotés placés sur l'image
Nombres (temps, tailles, compteurs, performances)Graphique à barres SVG en ligne à l'échelle, avant vs après
État ou cycle de vieMermaid stateDiagram-v2
Séquence de travail (migration, modification en plusieurs étapes)Étapes numérotées (uniquement si l'ordre est réel)
Code cléCourts extraits de diff (5–25 lignes) avec les lignes importantes marquées, à l'intérieur de <details> pour qu'ils ne dominent pas

Visez au moins trois visuels distincts pour un changement de taille fonctionnalité, et au moins un pour tout ce qui est plus petit. Les diagrammes doivent décrire le mécanisme réel (vrais noms de fonctions, vrais noms de fichiers, vraies valeurs), pas des boîtes génériques.

5. Construisez la page à partir du modèle

Copiez <skill-dir>/template.html et remplissez-le. Il contient déjà le look sketchpad (un thème clair volontairement : fond papier quadrillé, titres manuscrits, cartes crayonnées, diagrammes dessinés à la main), la mise en page et chaque composant listé ci-dessus. N'ajoutez pas de mode sombre et ne changez pas l'apparence sauf si l'utilisateur le demande. Règles :

  • Conservez le bloc <style> et le script de chargement Mermaid ; remplacez le contenu d'exemple. Supprimez les sections qui ne s'appliquent pas plutôt que de les laisser maigres (ex. pas de "Avant → après" pour un simple refactoring).
  • <title> : le nom de la fonctionnalité, deux à quatre mots (ex. "Logique de relance du paiement"), pas "Résumé du travail : …".
  • Hero : une phrase sur le résultat, la ligne méta (branche, lien PR, date) et la bande de statistiques (fichiers, lignes +/−, commits, vérifications réussies). Calculez les chiffres à partir de gather.sh, n'estimez pas.
  • Nécessite votre intervention (note autocollante sous le hero) : uniquement les vraies demandes qui attendent l'utilisateur, une ligne chacune, indiquant où regarder. Au maximum trois. Supprimez toute la note quand il n'y en a pas ; ne l'allongez jamais.
  • Pourquoi ainsi (tableau des décisions) : deux à quatre options qui ont réellement été pesées pendant la session, une marquée Choisie, un compromis en une ligne chacune. N'inventez pas d'alternatives pour remplir ; si aucune décision réelle n'a été prise, supprimez la section.
  • Gardez la page légère : ces deux sections plus celles qui s'appliquent. N'ajoutez pas de sections au-delà du modèle.
  • Arborescence des fichiers : une ligne par fichier significatif (regroupez les fichiers générés/binaires en une seule ligne), largeurs des barres +/− en pourcentage du total du plus gros fichier, plus une ligne en français simple expliquant pourquoi il a changé.
  • Extraits de diff : échappez <, >, &. Marquez les lignes avec class="add", class="del", ou class="hl" (ligne importante non modifiée).
  • Mermaid va dans <pre class="mermaid">, commençant directement après la balise avec le bloc de configuration du modèle (--- / config: / look: handDrawn / theme: neutral / ---) pour qu'il s'affiche dessiné à la main à la fois comme fichier local et sur claude.ai. Conservez la ligne classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px du modèle. Échappez </> dans les étiquettes sous forme de &lt;/&gt;, et utilisez class <ids> changed pour ce que ce travail a ajouté ou modifié. Gardez chaque diagramme à environ 5–9 nœuds pour qu'il tienne sur un écran : fusionnez les étapes consécutives en un seul nœud avec une ligne de détail <br/>, et divisez un flux plus long en deux diagrammes. Utilisez flowchart LR pour les courtes chaînes, TD pour celles qui bifurquent.
  • Vérification : listez chaque vérification avec une pastille réussite / échec / non vérifié et sa preuve (extrait de sortie ou capture d'écran). Les éléments "non vérifiés" sont requis lorsqu'ils existent.
  • Écrivez simplement : des phrases courtes, les termes de l'utilisateur, pas de remplissage.

Enregistrez-la sous <depot-racine>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html. Gardez ce dossier hors de git dans chaque dépôt sans toucher à son .gitignore, en l'ajoutant au fichier d'exclusion local une fois :

mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")

6. Vérifiez une fois, puis livrez

  1. Ouvrez-la une fois dans le panneau navigateur (preview_start avec url: file://<chemin>, ou le serveur statique du projet) et prenez une capture d'écran pour confirmer que les diagrammes se sont rendus et que rien ne déborde. Corrigez ce que ce seul affichage montre ; ne bouclez pas.
  2. Affichez-la dans le panneau latéral : SendUserFile avec display: "render".
  3. Publiez-la en tant qu'Artifact privé (Artifact publish avec le chemin du fichier, icon: "document", et une description d'une phrase) pour qu'elle survive après le nettoyage d'un worktree. C'est la copie persistante ; les artefacts commencent privés. Si aucun outil Artifact n'est disponible (ex. une session terminal simple), ignorez cette étape et donnez le chemin local.
  4. Dans le chat, après votre récapitulatif normal, ajoutez une ligne avec le lien de la brochure et le chemin du fichier local.

Mise à jour : si l'utilisateur demande des modifications, modifiez le même fichier et republiez-le au même chemin pour que le lien reste valide.

À quoi ressemble une bonne brochure

  • Une personne qui n'a pas participé à la session comprend ce qui a changé et pourquoi en moins de deux minutes de défilement.
  • Le premier écran répond à "qu'est-ce qui est différent maintenant ?" sans avoir à défiler.
  • Chaque diagramme, graphique et capture d'écran concerne ce changement.
  • Le statut honnête est visible : ce qui a été vérifié, ce qui ne l'a pas été, ce qui reste à faire.

Skills associés