paulmil11/decks

Que fait decks ?

L'utilisateur révise un deck dans le navigateur. Il tape un commentaire sous une diapositive (ou modifie le texte directement dessus), puis dit « process changes » ou clique sur Ask Claude dans le deck, ce qui copie une invite nommant le fichier du deck et les étapes sb ci-dessous ; traitez cette invite comme « process changes » pour ce deck. Vous agissez sur chaque commentaire, répondez sur la diapositive elle-même, vérifiez votre travail et exportez. Gardez le résumé de chat court : les réponses sur les diapositives portent les détails.

Où se trouvent les choses

• Le dossier de l'application est le dépôt Decks : le dossier dans lequel cette compétence est livrée (.claude/skills/decks/ à l'intérieur), ou, pour une copie de cette compétence dans ~/.claude/skills/, là où l'utilisateur l'a clonée. L'invite Ask Claude le nomme. Il contient server.py, la ligne de commande sb, le shell du navigateur dans static/, les modèles dans templates/ et les outils headless dans tools/. Exécutez sb à partir de là : ./sb ....
• Le serveur : python3 server.py, sur http://localhost:8790/ sauf si config.json ou SB_PORT disent le contraire. Si sb dit que le serveur n'est pas joignable, démarrez-le (en arrière-plan) et réessayez. sb le trouve à SB_URL, ou sur le port configuré.
• Les decks vivent dans le dossier decks (par défaut ~/slide-decks), un dossier par deck, listés dans decks.json là-bas. ./sb decks les liste avec leurs adresses.
• Ouvrez un deck à http://localhost:<port>/d/<slug>/<entry>. #s=<slide-id> saute à une diapositive, et #v=<version>&s=<id> sélectionne une version.
• L'état sauvegardé se trouve à côté de chaque deck dans .slidebuilder/ :
  • state.json : les modifications, commentaires et ordre des diapositives du relecteur, reflétés depuis la page. Ne jamais écrire à la main.
  • review.json : vos réponses, cycles et badges modifiés. Écrivez-le via sb.
• Chaque dossier de deck est un dépôt git. Les PDF, zip et fichiers PPTX sont ignorés.

La page

• Quatre vues : Focus (F), Scroll (S), Sorter (G) et Checks (C). Le filmstrip sur la gauche se réorganise par glisser-déposer.
  • Dans Focus et Scroll, la boîte de commentaires se trouve sous chaque diapositive, avec votre réponse en dessous. La barre de droite contient les notes de la diapositive et ce qui a changé.
  • Checks a cinq vérifications, touches 1 à 5 : le test des 5 secondes (première impression), le test des 10 secondes (lisibilité ; un échec laisse un commentaire sur la diapositive pour le cycle suivant), le flux horizontal (les titres seuls, modifiables sur place), le flux vertical (le titre en premier, le corps caché jusqu'à révélation) et Guides.
  • Les commentaires peuvent provenir de Checks : « Five-second test : … » et « Ten-second test : … » après un test chronométré manqué, et « Guides : … » de Ask Claude pour corriger dans Checks › Guides, en nommant ce que la diapositive enfreint. Corrigez la diapositive pour qu'elle passe, comme tout commentaire.
  • H masque tout sauf les titres. ? liste chaque raccourci.
• Ajouter une diapositive (N, « + Slide », ou le + entre les diapositives) suggère des mises en page et peut en ajouter une que le deck propose. Son invite Copie vous donne le fichier du deck, la position et ce que la diapositive doit dire. Lorsqu'une invite dit « I just added a … slide (LIBRARY['id']) », remplissez cette diapositive ; lorsqu'elle dit « add a new slide … », construisez-la dans le fichier du deck à cette position.
• Lorsque le relecteur modifie un titre dans Checks, c'est une modification en ligne : intégrez-la comme toute autre.
• Masquer le travail client (un interrupteur du tableau de bord, settings.json dans le dossier decks) est pour l'enregistrement ou le partage d'écran. Lorsqu'il est activé, le serveur omet les decks marqués client et les versions listées dans clientVersions. Ne montrez jamais les noms des clients à l'écran lorsqu'il est activé.

Un cycle (« process changes »)

1. cd vers le dossier de l'application.
2. ./sb comments <deck> liste les commentaires sur lesquels agir, numérotés comme le deck. Les brouillons sont ignorés. ./sb edits <deck> montre les modifications de texte en ligne et les déplacements de diapositives du relecteur. Les deux lisent depuis le disque, vous n'avez donc pas besoin de leur onglet de navigateur.
3. ./sb status <deck> "Reading your 9 comments" --done 0 --total 9. Le relecteur voit cela en direct dans la barre supérieure. Mettez à jour au fur et à mesure.
4. Pour chaque commentaire :
   • ./sb working <deck> <slide>.
   • Effectuez la modification dans le fichier du deck.
   • ./sb reply <deck> <slide> done "une phrase simple sur ce qui a changé".
   • Si vous avez besoin de l'avis du relecteur, utilisez question au lieu de done. Pour quelque chose que vous avez délibérément laissé de côté, utilisez skipped et dites pourquoi.
   • Un commentaire à moitié tapé reçoit une réponse question, pas une supposition.
5. Intégrez les modifications en ligne du relecteur dans le fichier du deck (leur modification l'emporte). Git contient l'ancienne version.
6. Vérifiez chaque diapositive que vous avez touchée :
   • ./sb shot <deck> <ids…>, puis regardez chaque image.
   • ./sb audit <deck> détecte les débordements, les étiquettes qui se chevauchent et tout ce que Guides signale.
   • ./sb comments <deck> ne devrait montrer rien de nouveau et de non traité.
7. Terminez :
   • ./sb export <deck> écrit le prochain PDF numéroté à partir du fichier du deck et déplace les plus anciens vers _archive/. Si le navigateur contient encore des modifications non intégrées, il le dit : intégrez-les d'abord. --with-edits exporte exactement ce que le navigateur montre à la place.
   • ./sb round <deck> --summary "…" --changed id="ce qui a changé" … --export vN.
   • ./sb commit <deck> "Round N : …".
   • ./sb idle <deck>.
   • Dites à l'utilisateur où se trouve le PDF.
8. La page se recharge d'elle-même une fois que le relecteur a fini de taper. Ne rechargez pas et ne fermez pas leur onglet. Dans le chat : quelques lignes, plus tout ce qui nécessite leur décision.

De nouveaux commentaires peuvent arriver pendant que vous travaillez. Exécutez ./sb comments à nouveau avant de terminer.

Le relecteur efface les commentaires traités avec « Looks good ». Ne les ajoutez pas à DONE_FB ; cette liste est uniquement pour les copies ouvertes en dehors de Decks, comme un fichier envoyé à quelqu'un d'autre.

Le fichier de deck

• Un fichier HTML autonome par deck, avec trois parties que vous modifiez :
  • contenu : entrées LIBRARY ('id': { cat, layout, title, …, notes }), regroupées en parties par cat (les parties sont CATS, nommées dans CAT_LABELS)
  • figures : FIGS fonctions renvoyant du SVG en ligne
  • versions : PITCHES (chacune un nom et une liste d'id de diapositives)
• La version par défaut est l'ordre de LIBRARY dans chaque partie. Pour réorganiser, déplacez les entrées de LIBRARY. Un ordre enregistré qui équivaut à un ancien ordre par défaut suit le fichier.
• Retirez une diapositive avec alt:true (elle va dans l'étagère du Sorter) et mettez son remplacement juste avant. Ne supprimez pas les diapositives de l'utilisateur. Une version alternative d'une diapositive reçoit prop:true, replaces:'…' (marquée « Proposed »).
• Une ligne de source va dans le pied de page via src:'Source : …', pas un sous-titre.
• Couleurs, police de titre et logo : un bloc <style id="deck-theme"> dans le fichier du deck, et LOGO pour le logo du deck dans img/. Restylez en modifiant ce bloc, pas les diapositives individuelles. Sans LOGO, les diapositives n'ont pas de logo.
• Changements visuels importants (une nouvelle mise en page, une refonte) : montrez d'abord à l'utilisateur une maquette ou deux options, puis construisez.
• Lorsque l'utilisateur veut un fichier à envoyer à quelqu'un, c'est le menu ⋯ Client copy : la version à l'écran avec uniquement les diapositives (pas de notes, commentaires, diapositives animateur, autres versions ou édition), les images à l'intérieur, avec un bouton Present. Editable copy est le deck complet avec notes et commentaires : n'envoyez jamais celui-ci à un client.
• Les decks sont retirés du tableau de bord avec ./sb hide <deck> (revenu avec ./sb show). ./sb delete <deck> --yes déplace un deck créé par cette application vers la Corbeille et ne désenregistre qu'un deck dans un dossier propre à l'utilisateur. Ne supprimez que lorsque l'utilisateur le demande.
• Le téléchargement d'images ou de logos nécessite l'accord de l'utilisateur à chaque fois. Dites-lui le nom du fichier, la source, la taille et la licence, et mettez le crédit dans le pied de page.

La méthode

Decks est construit sur la méthode que Paul Millerd enseigne à StrategyU. Appliquez-la à chaque diapositive que vous écrivez ou corrigez. Si la compétence strategy-slides est installée, elle contient la version complète : utilisez-la pour les storylines, les titres et les retours.

Réponse d'abord. Commencez par la recommandation, puis le contexte, puis les preuves. Construisez jusqu'à la recommandation (situation et complication, puis les idées clés) uniquement pour un public sceptique.

Ghost deck d'abord. Avant de construire un corps de diapositive, écrivez chaque titre d'action dans l'ordre et lisez-les comme un paragraphe. Si le paragraphe ne fait pas l'argument, corrigez les titres ou l'ordre maintenant ; c'est le point le moins coûteux pour corriger l'histoire. Notez ce que chaque corps doit montrer pour prouver son titre.

Flux vertical : le titre est le point à retenir, et le corps le prouve.

• Chaque titre est un titre d'action : une phrase complète qui énonce le point. « Q3 revenue grew 22%, driven by enterprise expansion », jamais « Q3 Revenue ».
• Poussez au-delà des titres vagues. « The company is improving » est l'étape un ; « Profitability increased for the first time in 5 years due to supply chain investments » est l'objectif.
• Pas de boîtes « key takeaway » ou de bandes résumé en bas. L'insight mène la page.
• Utilisez des verbes simples avec leurs objets naturels. Ne personnifiez pas les données et ne forcez pas de métaphores sur les chiffres. Pas de fragments avec virgule-pivot (« One mode of thinking, when the work needs two »). Deux lignes au maximum. Lisez à voix haute : cela devrait ressembler à quelque chose qu'une personne dirait à un collègue.
• Les titres uniquement numériques sont vides. « Three risks and how we cover them » devient la conclusion : « The real exposure is West Coast service, not warehouse capacity. »
• Les couvertures, les séparateurs de section et le séparateur d'annexe sont exemptés. La diapositive de clôture ne l'est pas : « Approuvez d'ici le 14 mars et nous quittons les deux baux avant leur renouvellement », pas « Prochaines étapes ».

Flux horizontal : les titres seuls racontent l'histoire. Lisez-les dans l'ordre (Checks › Horizontal flow). S'ils n'ont pas de sens sans les corps des diapositives, corrigez les titres ou l'ordre.

Une idée par diapositive. Si une diapositive a besoin de « et aussi », elle a besoin d'être deux diapositives.

Les tests des cinq et dix secondes concernent la lisibilité. Une diapositive présentée fait passer son point principal en cinq secondes. Une diapositive que les gens lisent peut être comprise en dix secondes : un point principal, une hiérarchie lisible, un graphique dont la forme se lit sans étude. Les murs de texte, un chiffre clé enterré dans un tableau dense, et plusieurs idées non liées sur une seule diapositive échouent tous.

« So what ? » est un test séparé. Trois boîtes soignées lisant Innovation, Excellence, Growth passent le test des dix secondes et échouent à « so what ? » (syndrome de la jolie diapositive). Chaque diapositive dit au public quoi penser. Gardez les deux conclusions séparées lorsque vous donnez des retours.

Les graphiques prouvent le titre. Écrivez le message avant de dessiner le graphique. Les barres, les colonnes et les lignes couvrent presque tout ; n'utilisez jamais de diagramme circulaire. Le nombre qui compte est la marque la plus proéminente, tout ce que le titre nomme (une récession, un point d'inflexion) est marqué sur le graphique, et tout ce qui ne soutient pas le titre disparaît. Les données incertaines reçoivent une étiquette « Illustrative » et une note sur les hypothèses.

Le résumé exécutif est la diapositive la plus importante : la recommandation comme titre, et trois insights avec une ligne de preuve chacun. Utilisez les séparateurs de section uniquement dans les longs decks (20+ diapositives) avec des sections distinctes.

Présenté ou lu. Présenté : moins de 20 mots dans le corps, une idée, des visuels larges. Lu : plus de texte est acceptable, avec des mots-clés en gras, et chaque diapositive se suffit à elle-même car elle sera transmise.

Donner des retours sur un deck. Lisez d'abord tout le deck. Donnez ensuite, dans l'ordre : l'histoire (les titres en séquence, ce qu'ils disent, et ce qui manque ou est dans le désordre) ; les diapositives qui posent problème, avec la correction (écrivez le nouveau titre quand le titre est le problème) ; et les trois changements les plus importants, avec l'argument et l'ordre avant les polices et les couleurs. Si l'argument ne tient pas, dites-le d'abord. Vérifiez chaque numéro de diapositive avant de le citer.

Écriture. Verbes actifs, contractions et chiffres plutôt que des adjectifs. Jamais : delve, landscape, leverage, utilize, crucial, pivotal, robust, seamless, transformative, underscore, additionally, moreover, furthermore. Un tiret em par diapositive au maximum.

Règles de style des diapositives

En plus de la méthode :

• Pas de lignes petites, atténuées ou en italique en bas des cartes ou des boîtes. Intégrez tout ce qui est important dans l'élément auquel il appartient.
• Pas de grilles de cartes identiques. Dessinez plutôt la relation : un processus, un spectre, une échelle, un graphique ou une carte.
• Les instructions sont une phrase simple. Les questions de réflexion sont simples et portent sur le propre travail du public.
• Temps d'ordre du jour par blocs de 5 minutes.
• Utilisez le propre matériel, diagrammes et formulations de l'utilisateur avant d'inventer des cadres. Lorsque vous coupez, coupez d'abord les diapositives inventées, et gardez les paires construction/révélation et configuration/résultat intactes.
• Marquez le texte que vous avez rédigé dans les notes, afin que l'utilisateur puisse le remplacer.
• Les citations et les chiffres proviennent uniquement de sources que vous avez ouvertes dans la session, cités exactement et attribués à qui les a réellement dits.
• Tout passe Checks › Guides : la bordure protégée, les titres sur deux lignes, rien en dessous de 12 px, au maximum quatre tailles de texte sur une diapositive. Ce sont des directives, pas des règles ; corrigez ce que sb audit liste, ou dites pourquoi une diapositive est une exception.

Démarrer un nouveau deck

L'utilisateur démarre les decks depuis le formulaire New deck du tableau de bord, en deux étapes. Étape 1 : un nom, ce qu'il construit (une présentation, une formation, un exposé, une proposition ou un deck vierge), et les pièces à construire à côté. Étape 2 : pour qui c'est, ce qu'ils savent et ce qui les intéresse, le point principal, et la longueur facultative, le type de public, la structure, la densité, les couleurs, la police de titre, le logo et les notes. Create deck crée le dossier, lui donne son propre préfixe de stockage, l'ajoute à decks.json, commence son historique git, écrit le brief dans BRIEF.md, copie une invite dans son presse-papiers et ouvre le deck. Lorsqu'il colle cette invite :

1. Lisez BRIEF.md dans le dossier du deck et adaptez le modèle à celui-ci avant d'écrire les diapositives. Le modèle est un point de départ, pas une forme fixe :
   • Comment il sera utilisé. Présenté : une idée par diapositive, grands caractères, peu de texte ; il doit passer le test des 5 secondes. Envoyé pour être lu : chaque diapositive se suffit à elle-même avec un corps plus complet ; il doit passer le test des 10 secondes. Présenté, puis envoyé : diapositives présentables, avec les détails dans les notes ou une annexe.
   • Public et ce qu'il sait. Ajustez le vocabulaire, les exemples et combien vous expliquez ; les cadres reçoivent la réponse en premier.
   • Structure. Réponse d'abord : la recommandation, puis les raisons. Situation, complication, résolution : dans cet ordre. Une histoire en quelques parties : sections avec séparateurs. Enseigner, pratiquer, réfléchir : modules avec exercices et questions de réflexion.
   • Densité. Clairsemée, équilibrée ou détaillée, comme le disent les mots.
   • Tout ce qui est laissé en blanc est à votre...