d3group/d3-explainer

D3 Explainer (HTML interactif, pour les auteurs eux-mêmes)

<skill-dir> dans cette compétence désigne le répertoire de base de la compétence elle-même, que Claude Code affiche lors du chargement de la compétence (installée comme un plugin : ${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer ; copiée à la main : ~/.claude/skills/d3-explainer). Remplacez le chemin réel dans chaque commande. <wording-dir> désigne <skill-dir>/../d3-scientific-wording, la compétence de formulation partagée fournie par chaque plugin D3.

Un fichier HTML hors ligne qui explique un projet de recherche aux personnes qui l'écrivent : quelle est la question, quelle lacune il comble, comment l'idée centrale fonctionne, comment se déroule chaque dérivation et pourquoi, où tout cela se trouve dans le code, ce que montrent les preuves, et ce qui reste ouvert. Les figures interactives portent l'intuition ; le texte reste proche des sources et le mentionne.

Le lecteur est l'auteur et ses co-auteurs. Cela décide presque tout ce qui suit :

• Ils connaissent le domaine. Sautez les prérequis de manuel sauf si leurs notes montrent un point faible.
• Ils veulent comprendre, donc l'honnêteté prime sur le polissage : les hypothèses, les désaccords papier-code, et les questions ouvertes ont leur propre section, et les interprétations sont signalées comme telles.
• Ils vérifieront les affirmations par rapport à leurs propres fichiers, donc chaque affirmation substantielle pointe vers sa source, et la construction vérifie que le pointeur existe.
• Le détail est bienvenu, l'exhaustivité ne l'est pas. La profondeur que seuls certains lecteurs souhaitent va dans des blocs repliés. « Tous les détails » n'arrive que lorsque l'utilisateur le demande, et seulement pour la partie qu'il nomme.

Tout Python s'exécute via uv (uv run, uv run --with <pkg>) ; jamais pip, jamais d'installation globale.

Fichiers de référence (chargement à la demande)

Fichier	Charger quand
references/scanning.md	Phase 1 : lire un dépôt avec un budget de tokens, les niveaux d'entrée, le vault / recall / NotebookLM, les explicateurs précédents
references/content-design.md	Phases 2 et 3 : squelette des sections, budgets de profondeur, comment présenter le verrou et les dérivations, inventaire honnête, ce qui est spécifique à la formulation de l'explicateur (les règles elles-mêmes : d3-scientific-wording)
references/components.md	Phase 3 : le vocabulaire HTML, les puces de source, les directives de construction, explainer.toml, l'API JavaScript D3X
references/visualization.md	Phases 2 et 3 : concevoir des figures interactives qui enseignent ; catalogue de motifs ; pièges
references/review.md	Phase 4 : les deux invites du relecteur, les règles de tokens, la boucle
assets/example/	Un petit dépôt avec un explicateur terminé. Lisez assets/example/explainer/sections/*.html une fois pour les motifs fonctionnels de chaque composant. Ne le copiez jamais dans un projet utilisateur.

Étape 0 : demander une fois

Sauf si l'utilisateur l'a déjà dit, demandez cela en un seul message, puis ne demandez plus :

Périmètre. L'ensemble du projet, ou une partie (un modèle, une dérivation, un pipeline) ? Profondeur. focus (une idée ou une dérivation : 1 à 3 sections, une ou deux figures, environ 5 min), overview (4 à 6 sections, environ 10 à 15 min de lecture), standard (par défaut : 7 à 10 sections, 4 à 8 figures interactives, 1 à 3 dérivations, 20 à 35 min), ou deep (jusqu'à 14 sections). « Deep on X » signifie standard plus une section d'approfondissement sur X. Révision. light : vérifications automatisées plus mes propres contrôles numériques, presque pas de tokens supplémentaires. single : un agent relecteur couvre à la fois la fidélité et les figures, un tour, environ 50 à 70k tokens. standard : deux agents relecteurs en parallèle (fidélité aux sources ; figures et interaction), un tour, environ 100 à 150k tokens ensemble. Le coût d'un relecteur est surtout un plancher fixe et dépend à peine de la taille du projet, donc ma recommandation suit la profondeur : focus light, overview single, standard et deep la révision à deux agents. full : les deux agents bouclent jusqu'à ce que chaque score soit 9 sur 10, limité à trois tours, deux à trois fois le coût de standard. Formulation. ste (par défaut : Simplified Technical English selon ASD-STE100, au plus 25 mots par phrase, voix active, un sens par mot ; le plus simple pour les co-auteurs qui lisent l'anglais comme langue seconde) ou standard (la formulation scientifique du groupe sans les limites STE).

« rapide », « pas de révision », « pas cher » ou « peu de tokens » signifie light. « approfondi » signifie full. « juste cette dérivation », « explique seulement X », « garde ça court » signifie focus. « normal », « STE » ou rien dit signifie formulation ste ; « formulation normale », « style article » ou « pas de STE » signifie standard. Rien dit signifie profondeur standard, et la révision recommandée pour cette profondeur.

Quand personne ne peut répondre (un batch ou une exécution par agent) : prenez les valeurs par défaut, décidez chaque point que cette compétence demanderait, enregistrez chaque décision dans la section 0 de brief.md, et continuez. Le brief est alors l'endroit où l'auteur peut voir ce qui a été décidé pour lui.

Flux de travail

Affichez une ligne de statut avec horodatage à chaque limite de phase, comme le font les autres compétences D3 : [HH:MM:SS] PHASE: ....

Phase 1 : Cartographier le projet (lire à moindre coût, dans le bon ordre)

uv run <skill-dir>/scripts/scan.py            # depuis la racine du dépôt ; ajoutez --out explainer/scan.md pour le conserver

Le scan rapporte le niveau d'entrée (A : code et papier, B : papier uniquement, C : code uniquement, D : PDF uniquement, E : notes uniquement), la date de dernière modification des documents d'orientation, du papier et de chaque dossier de code (un CLAUDE.md obsolète ou une approche abandonnée apparaît ici), le plan du papier avec ses étiquettes d'équations, les plus grands modules de code avec les noms de symboles et les numéros de ligne, les fichiers de résultats intégrables, le vault avec les notes de l'auteur par dossier, les explicateurs précédents, et une estimation de tokens pour chaque document d'orientation, papier, fichier de section, module de code et note. Affichez INPUT TIER: X et laissez l'utilisateur le modifier.

Ensuite, lisez, dans cet ordre, et arrêtez-vous lorsque le brief peut être rédigé. Les détails et les budgets sont dans references/scanning.md.

1. Documents d'orientation (CLAUDE.md, README, notes d'analyse ou de spécification à la racine).
2. Le papier : résumé, introduction, déclaration de contribution, puis les sections sur le modèle et la méthode. Parcourez les résultats pour les chiffres clés.
3. Les explicateurs précédents trouvés par le scan : le plan (scan.py --explainer <file>), puis une section complète pour le ton (--section N). Ils montrent ce que l'auteur comprend déjà et la voix qu'il apprécie. Bâtissez dessus ; ne les répétez pas.
4. Vault : aperçu, concept, verrou, notes de décision et de question ouverte, choisies par titre. Pas le dépôt de littérature.
5. Code : uniquement les modules qui réalisent l'idée centrale, trouvés via la carte des symboles. Pour une base de code large (plus d'environ 40 fichiers ou 8 000 lignes), envoyez un sous-agent Explore pour produire la carte papier-à-code et conservez sa conclusion, pas les fichiers.

Enrichissement optionnel, proposé uniquement lorsque le verrou ou l'historique du projet est mince dans le dépôt : la compétence recall (ce qui a été décidé, et quand) ou NotebookLM (ce que dit la littérature). Même protocole que dans d3-abstract. Lorsque le scan a trouvé un dossier de littérature, un vault avec des sources importées ou un notebook NotebookLM, proposez dans la même question un profil thématique de d3-scientific-wording (Étape 1b) : il montre quel terme et quelle orthographe la littérature utilise pour chaque concept, ce qui alimente le tableau de notation et la feuille de termes. Affichez ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile].

Phase 2 : Brief de contenu, approuvé avant tout HTML

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # crée ./explainer : explainer.toml, brief.md, sections/, d3x/
#   plusieurs papiers dans le dépôt : ajoutez --paper <dossier>         explicateur ailleurs : init.py <dossier> --repo <racine du dépôt>

Emplacement de sauvegarde : <repo>/explainer/, à la racine du dépôt externe (pas à l'intérieur du sous-module du papier : Overleaf n'en a pas besoin). Confirmez l'emplacement dans le même message que le brief.

Remplissez explainer/brief.md : le projet en deux phrases, ce que le lecteur devrait être capable de faire après, les sources lues et délibérément non lues, le verrou, le plan des sections, les dérivations, l'inventaire honnête, ce qui est laissé de côté volontairement, et le brief de formulation sous un titre ## Wording (genre explicateur, lecteurs les co-auteurs, domaine, le mode de formulation choisi, et une feuille de termes pour les constructions et symboles du projet). Le plan des sections a une ligne par section et, pour chaque figure interactive, sa phrase bouton-vers-intuition : « déplacer X montre que Y ». Une figure sans une telle phrase est de la décoration et est supprimée ici, pas après sa construction.

Affichez le brief dans le chat sous forme compacte et obtenez une approbation. C'est le seul point de contrôle obligatoire : il coûte quelques centaines de tokens et évite d'écrire les mauvaises 6 000 mots. N'écrivez pas de sections avant cela.

Phase 3 : Écrire, une section à la fois

Invoquez d3-scientific-wording avant la première section (Outil de compétence : d3-scientific-wording:d3-scientific-wording ; lorsqu'il n'est pas listé, lisez <wording-dir>/SKILL.md), avec le brief de brief.md. En mode ste, lisez aussi <wording-dir>/references/ste.md. Chargez references/components.md et references/visualization.md, et parcourez les sections d'exemple une fois ; elles sont écrites en STE.

• Un fichier par section : explainer/sections/NN-slug.html, exactement une <section id=... data-nav=... data-kicker=...> chacun. La construction les numérote et crée la navigation.
• Construisez après chaque section, pour que les erreurs restent locales : uv run explainer/d3x/build.py --draft (les marqueurs TODO et les liens vers des sections pas encore écrites ne génèrent qu'un avertissement)
• Ordre à l'intérieur d'une section d'idée centrale : phrase simple, figure interactive, énoncé formel, dérivation, où cela se trouve dans le code. L'intuition d'abord, l'algèbre ensuite.
• Laissez le dépôt parler au lieu de le retaper. <div class="eq" data-label="eq:prob"></div> extrait l'équation du .tex du papier (avec son numéro, si un .aux existe). <pre class="code" data-src="src/model.py" data-lines="88-104"></pre> extrait les vraies lignes. Les deux sont moins coûteux que la frappe et ne peuvent pas dériver de la source.
• Pointez vers les sources avec des puces : [[paper:eq:prob]], [[code:src/model.py:88 def solve]], [[vault:Note name]], [[result:results/table.csv]], et [[reading]] pour votre propre interprétation. La construction échoue sur un fichier, une ligne, un symbole, une étiquette ou une note qui n'existe pas ; une puce de vault ne génère qu'un avertissement tant qu'aucun vault n'est configuré dans explainer.toml. Une puce échouée est une découverte sur votre compréhension : corrigez l'affirmation, ne supprimez pas la puce.
• Les figures interactives montrent, par ordre de préférence : les fichiers de résultats du dépôt ; les nombres calculés par le propre code du dépôt sur une grille (un petit explainer/data/make_data.py, voir visualization.md) ; ou la formule réelle réimplémentée à l'échelle jouet dans le navigateur, déclarée toy: true, ce qui place un badge visible « jouet illustratif » dessus. Les valeurs par défaut sont celles du papier. Les nombres sont intégrés à partir de fichiers, jamais saisis de mémoire.
• Chaque légende de figure commence par {fig} (la construction numérote les figures ; référencez-en une comme {fig:figure-id}) et dit quoi essayer et quoi remarquer.

Phase 4 : Vérifier

uv run explainer/d3x/build.py                  # pas de --draft : les marqueurs TODO échouent maintenant ; affiche les mots par section par rapport au budget de profondeur
uv run explainer/d3x/check.py --shots          # navigateur sans tête : déplace chaque contrôle, glisse chaque poignée, parcourt chaque dérivation

check.py doit se terminer par 0 error(s). Ensuite, relisez la formulation des sections (omettez --ste en mode standard) ; corrigez chaque erreur et décidez chaque avertissement :

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

Cela détecte ce que la lecture de la source ne peut pas : NaN dans un chemin, un contrôle qui ne change rien, une formule que MathJax ne peut pas afficher, une étiquette tronquée à une extrémité du curseur, un débordement de page à la largeur d'un téléphone. Son premier lancement sur une machine peut demander un navigateur une fois : uv run --with playwright playwright install chromium (il se rabat sur un Chrome ou Edge installé).

Regardez vous-même deux ou trois des captures d'écran dans explainer/review/shots/. Ensuite, révisez à la profondeur choisie ; les invites et les règles de tokens sont dans references/review.md :

• single : un relecteur en lecture seule avec l'invite fusionnée de references/review.md, lisant les deux paquets, check.md et les captures d'écran en un tour. Ensuite, vérifiez et appliquez comme ci-dessous.
• light : pas d'agents relecteurs. Faites vous-même un passage sur les nombres : chaque nombre dans le texte, les tuiles KPI et les valeurs par défaut des figures par rapport au papier ou au fichier de résultats cité. Puis arrêtez-vous.
• standard : deux relecteurs en lecture seule en parallèle, un tour. Chaque construction écrit deux paquets dans explainer/review/ : fidelity-packet.md (le texte de l'explicateur avec les numéros de ligne, les étapes de dérivation avec leurs raisons, et pour chaque puce l'équation citée ou les lignes de code comme preuve) et figures-packet.md (légende et script de chaque figure). Le relecteur de fidélité vérifie les dérivations, les nombres, les affirmations sur le verrou et la formulation (la lecture à froid et les règles de d3-scientific-wording) à partir du premier ; le relecteur d'expérience vérifie que chaque figure enseigne sa phrase bouton-vers-intuition à partir du second, plus check.md et les captures d'écran. Aucun n'a besoin de parcourir le dépôt, ce qui maintient la révision abordable. Ne modifiez pas les fichiers de section pendant leur exécution. Ensuite, vérifiez chaque bloqueur et majeur vous-même, appliquez-les, reconstruisez, relancez check.py. Un second examen n'a lieu que pour un bloqueur, uniquement par le relecteur qui l'a soulevé, uniquement sur les fichiers modifiés.
• full : les mêmes deux relecteurs, en boucle jusqu'à ce que chaque catégorie soit 9 ou mieux, limité à trois tours ; puis transmettez les points restants à l'utilisateur.

Phase 5 : Livrer

Donnez le chemin explainer/dist/<name>.html (un fichier, fonctionne hors ligne, sûr à envoyer par email), la profondeur de révision utilisée, et le tableau de résultats fusionné avec ce qui a été corrigé. Mentionnez : n ouvre le tiroir de notation, les dérivations avancent avec « Next step », les puces pointent vers des permaliens GitHub vers le commit construit lorsque le dépôt distant est sur GitHub. Si le dépôt a un vault, proposez de déposer une copie du HTML dedans, là où vivent les précédents explicateurs de l'auteur. Posez la question du filigrane de d3-scientific-wording (Étape 5) une fois ; en cas de réponse positive, nettoyez explainer/sections/*.html (jamais le fichier construit, qui intègre MathJax et les polices) et reconstruisez. Proposez de committer `e

[Le fichier a été tronqué, mais le reste concerne les commits, la configuration et les règles markdown standard.]