d3group/d3-explainer

D3 Explainer (HTML interactivo, para los propios autores)

<skill-dir> en esta habilidad significa el directorio base de la propia habilidad, que Claude Code muestra cuando la habilidad se carga (instalada como plugin: ${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer; copiada a mano: ~/.claude/skills/d3-explainer). Sustituye la ruta real en cada comando. <wording-dir> significa <skill-dir>/../d3-scientific-wording, la habilidad de redacción compartida que incluye cada plugin D3.

Un único archivo HTML offline que explica un proyecto de investigación a las personas que lo escriben: cuál es la pregunta, qué brecha cierra, cómo funciona la idea central, cómo va cada derivación y por qué, dónde reside todo en el código, qué muestran las pruebas y qué sigue abierto. Las figuras interactivas transmiten la intuición; el texto se mantiene cerca de las fuentes y lo indica.

El lector es el autor y sus coautores. Eso decide casi todo lo siguiente:

• Conocen el campo. Omite los antecedentes de libro de texto a menos que sus notas muestren que es un punto débil.
• Quieren entender, por lo que la honestidad supera al pulido: las suposiciones, los desacuerdos entre el artículo y el código, y las preguntas abiertas tienen su propia sección, y las interpretaciones se marcan como tales.
• Verificarán las afirmaciones contra sus propios archivos, por lo que cada afirmación sustancial apunta a su fuente, y la compilación verifica que el puntero exista.
• Elaborar está bien, ser exhaustivo no. La profundidad que solo algunos lectores desean va en bloques contraídos. "Cada detalle" ocurre solo cuando el usuario lo pide, y solo para la parte que nombra.

Todo Python se ejecuta a través de uv (uv run, uv run --with <pkg>); nunca pip, nunca instalaciones globales.

Archivos de referencia (cargar bajo demanda)

Archivo	Cargar cuando
references/scanning.md	Fase 1: leer un repositorio con presupuesto de tokens, niveles de entrada, vault / recall / NotebookLM, explicadores anteriores
references/content-design.md	Fase 2 y 3: estructura de secciones, presupuestos de profundidad, cómo presentar la brecha y las derivaciones, inventario honesto, qué es específico de la redacción del explicador (las reglas en sí: d3-scientific-wording)
references/components.md	Fase 3: el vocabulario HTML, chips de fuente, directivas de compilación, explainer.toml, la API JavaScript D3X
references/visualization.md	Fase 2 y 3: diseñar figuras interactivas que enseñen; catálogo de patrones; dificultades
references/review.md	Fase 4: los dos mensajes de revisor, reglas de tokens, el bucle
assets/example/	Un repositorio pequeño con un explicador terminado. Lee assets/example/explainer/sections/*.html una vez para ver patrones funcionales de cada componente. Nunca lo copies en un proyecto de usuario.

Paso 0: preguntar una vez

A menos que el usuario ya lo haya dicho, pregunta esto en un solo mensaje y luego no vuelvas a preguntar:

Alcance. ¿Todo el proyecto, o una parte (un modelo, una derivación, un pipeline)? Profundidad. focus (una idea o una derivación: 1 a 3 secciones, una o dos figuras, unos 5 min), overview (4 a 6 secciones, unos 10 a 15 min de lectura), standard (por defecto: 7 a 10 secciones, 4 a 8 figuras interactivas, 1 a 3 derivaciones, 20 a 35 min), o deep (hasta 14 secciones). "Deep en X" significa standard más una sección de inmersión profunda en X. Revisión. light: comprobaciones automatizadas más mi propio pase de números, casi sin tokens extra. single: un agente revisor cubre tanto fidelidad como figuras, una ronda, unos 50 a 70k tokens. standard: dos agentes revisores en paralelo (fidelidad a tus fuentes; figuras e interacción), una ronda, unos 100 a 150k tokens en conjunto. El costo de un revisor es principalmente un piso fijo y apenas depende del tamaño del proyecto, así que mi recomendación sigue la profundidad: focus light, overview single, standard y deep la revisión de dos agentes. full: los dos agentes iteran hasta que cada puntuación sea 9 de 10, con un máximo de tres rondas, de dos a tres veces el costo de standard. Redacción. ste (por defecto: Simplified Technical English según ASD-STE100, máximo 25 palabras por oración, voz activa, un significado por palabra; más fácil para coautores que leen inglés como segunda lengua) o standard (la redacción científica del grupo sin los límites del STE).

"quick", "no review", "cheap" o "short on tokens" significan light. "thorough" significa full. "just this derivation", "only explain X", "keep it short" significan focus. "plain", "STE" o nada dicho significan redacción ste; "normal wording", "paper style" o "no STE" significan standard. Nada dicho significa profundidad standard, y la revisión recomendada para esa profundidad.

Cuando nadie pueda responder (un lote o ejecución de agente): toma los valores predeterminados, decide cada punto sobre el que esta habilidad preguntaría, registra cada decisión en la sección 0 de brief.md y continúa. El brief es entonces el lugar donde el autor puede ver lo que se decidió por él.

Flujo de trabajo

Imprime un estado con marca de tiempo de una línea en cada límite de fase, como hacen las otras habilidades D3: [HH:MM:SS] PHASE: ....

Fase 1: Mapear el proyecto (leer de forma económica, en el orden correcto)

uv run <skill-dir>/scripts/scan.py            # desde la raíz del repositorio; añade --out explainer/scan.md para conservarlo

El escaneo informa el nivel de entrada (A: código y artículo, B: solo artículo, C: solo código, D: solo PDF, E: solo notas), cuándo se modificaron por última vez los documentos de orientación, el artículo y cada carpeta de código (un CLAUDE.md obsoleto o un enfoque abandonado se muestra aquí), el esquema del artículo con sus etiquetas de ecuación, los módulos de código más grandes con nombres de símbolos y números de línea, archivos de resultados incrustables, el vault con las notas del autor por carpeta, explicadores anteriores y una estimación de tokens para cada documento de orientación, artículo, archivo de sección, módulo de código y nota. Imprime INPUT TIER: X y permite al usuario anularlo.

Luego lee, en este orden, y detente cuando se pueda escribir el brief. Los detalles y presupuestos están en references/scanning.md.

1. Documentos de orientación (CLAUDE.md, README, notas de especificación o análisis en la raíz).
2. El artículo: resumen, introducción, declaración de contribución, luego las secciones de modelo y método. Hojea los resultados para ver los números principales.
3. Explicadores anteriores encontrados por el escaneo: el esquema (scan.py --explainer <file>), luego una sección completa para el tono (--section N). Muestran lo que el autor ya entiende y la voz que le gusta. Constrúyelos; no los repitas.
4. Vault: notas de visión general, concepto, brecha, decisión y preguntas abiertas, elegidas por título. No el volcado de literatura.
5. Código: solo los módulos que implementan la idea central, encontrados a través del mapa de símbolos. Para una base de código grande (más de unos 40 archivos o 8,000 líneas), envía un subagente Explore para producir el mapa artículo-a-código y conserva su conclusión, no los archivos.

Enriquecimiento opcional, ofrecido solo cuando la brecha o la historia del proyecto son escasas en el repositorio: la habilidad recall (lo que se decidió, y cuándo) o NotebookLM (lo que dice la literatura). Mismo protocolo que en d3-abstract. Cuando el escaneo encontró una carpeta de literatura, un vault con fuentes importadas o un cuaderno de NotebookLM, ofrece en la misma pregunta un perfil de tema de d3-scientific-wording (Paso 1b): muestra qué término y ortografía usa la literatura para cada concepto, lo que siembra la tabla de notación y la hoja de términos. Imprime ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile].

Fase 2: Brief de contenido, aprobado antes de cualquier HTML

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # crea ./explainer: explainer.toml, brief.md, sections/, d3x/
#   varios artículos en el repositorio: añade --paper <folder>         explicador en otro lugar: init.py <dir> --repo <repo root>

Ubicación de guardado: <repo>/explainer/, en la raíz del repositorio externo (no dentro del submódulo del artículo: Overleaf no tiene uso para él). Confirma la ubicación en el mismo mensaje que el brief.

Rellena explainer/brief.md: el proyecto en dos oraciones, qué debería poder hacer el lector después, fuentes leídas y deliberadamente no leídas, la brecha, el plan de secciones, las derivaciones, el inventario honesto, y qué se omite a propósito, y el brief de redacción bajo un encabezado ## Wording (género explicador, lectores los coautores, campo, el modo de redacción elegido y una hoja de términos para los constructos y símbolos del proyecto). El plan de secciones tiene una línea por sección y, para cada figura interactiva, su frase de control-a-insight: "mover X muestra que Y". Una figura sin esa frase es decoración y se elimina aquí, no después de construida.

Muestra el brief en el chat en forma compacta y obtén aprobación. Este es el único punto de control obligatorio: cuesta unos cientos de tokens y evita escribir las 6,000 palabras equivocadas. No escribas secciones antes de esto.

Fase 3: Escribir, una sección a la vez

Invoca d3-scientific-wording antes de la primera sección (Herramienta de habilidad: d3-scientific-wording:d3-scientific-wording; cuando no esté listada, lee <wording-dir>/SKILL.md), con el brief de brief.md. En modo ste, también lee <wording-dir>/references/ste.md. Carga references/components.md y references/visualization.md, y hojea las secciones de ejemplo una vez; están escritas en STE.

• Un archivo por sección: explainer/sections/NN-slug.html, exactamente un <section id=... data-nav=... data-kicker=...> cada uno. La compilación los numera y crea la navegación.
• Compila después de cada sección, para que los errores se mantengan locales: uv run explainer/d3x/build.py --draft (los marcadores TODO y los enlaces a secciones aún no escritas solo advierten)
• Orden dentro de una sección de idea central: oración simple, figura interactiva, declaración formal, derivación, dónde reside en el código. Primero la intuición, luego el álgebra.
• Deja que el repositorio hable en lugar de volver a escribirlo. <div class="eq" data-label="eq:prob"></div> extrae la ecuación del .tex del artículo (con su número, si existe un .aux). <pre class="code" data-src="src/model.py" data-lines="88-104"></pre> extrae las líneas reales. Ambos son más baratos que escribir y no pueden desviarse de la fuente.
• Apunta a las fuentes con chips: [[paper:eq:prob]], [[code:src/model.py:88 def solve]], [[vault:Note name]], [[result:results/table.csv]] y [[reading]] para tu propia interpretación. La compilación falla si un archivo, línea, símbolo, etiqueta o nota no existe; un chip de vault solo advierte mientras no haya vault configurado en explainer.toml. Un chip fallido es un hallazgo sobre tu comprensión: corrige la afirmación, no elimines el chip.
• Las figuras interactivas muestran, en orden de preferencia: los archivos de resultados del repositorio; números calculados por el propio código del repositorio en una cuadrícula (un pequeño explainer/data/make_data.py, consulta visualization.md); o la fórmula real reimplementada a escala de juguete en el navegador, declarada toy: true, que coloca una insignia visible "ejemplo ilustrativo" en ella. Los valores predeterminados se basan en la configuración del artículo. Los números se incrustan desde archivos, nunca se escriben de memoria.
• Cada pie de figura comienza con {fig} (la compilación numera las figuras; refiérete a una como {fig:figure-id}) y dice qué probar y qué notar.

Fase 4: Verificar

uv run explainer/d3x/build.py                  # sin --draft: los marcadores TODO ahora fallan; imprime palabras por sección contra el presupuesto de profundidad
uv run explainer/d3x/check.py --shots          # navegador sin cabeza: mueve cada control, arrastra cada manejador, recorre cada derivación

check.py debe terminar con 0 error(s). Luego, revisa la redacción de las secciones (omite --ste en modo standard); corrige cada error y decide cada advertencia:

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

Detecta lo que leer la fuente no puede: NaN en una ruta, un control que no cambia nada, una fórmula que MathJax no puede renderizar, una etiqueta cortada en un extremo del control deslizante, desbordamiento de página en ancho de teléfono. Su primera ejecución en una máquina puede pedir un navegador una vez: uv run --with playwright playwright install chromium (vuelve a un Chrome o Edge instalado).

Mira tú mismo dos o tres de las capturas de pantalla en explainer/review/shots/. Luego, revisa con la profundidad elegida; los mensajes y las reglas de tokens están en references/review.md:

• single: un revisor de solo lectura con el mensaje combinado de references/review.md, leyendo ambos paquetes, check.md y las capturas de pantalla en una ronda. Luego verifica y aplica como se indica a continuación.
• light: sin agentes revisores. Haz tú mismo un pase de números: cada número en el texto, los paneles de KPI y los valores predeterminados de las figuras contra el artículo o el archivo de resultados que citan. Luego detente.
• standard: dos revisores de solo lectura en paralelo, una ronda. Cada compilación escribe dos paquetes en explainer/review/: fidelity-packet.md (el texto del explicador con números de línea, los pasos de la derivación con sus razones, y para cada chip la ecuación citada o las líneas de código como evidencia) y figures-packet.md (pie de figura y script de cada figura). El revisor de fidelidad verifica derivaciones, números, afirmaciones de brecha y la redacción (la lectura en frío y las reglas de d3-scientific-wording) del primero; el revisor de experiencia verifica que cada figura enseñe su frase de control-a-insight del segundo, además de check.md y las capturas de pantalla. Ninguno necesita deambular por el repositorio, que es lo que mantiene la revisión asequible. No edites archivos de sección mientras se ejecutan. Luego verifica cada bloqueador y mayor tú mismo, aplícalos, recompila, vuelve a ejecutar check.py. Una segunda mirada ocurre solo para un bloqueador, solo por el revisor que lo planteó, solo en los archivos modificados.
• full: los mismos dos revisores, en bucle hasta que cada categoría sea 9 o mejor, con un máximo de tres rondas; luego entrega los puntos restantes al usuario.

Fase 5: Entregar

Proporciona la ruta explainer/dist/<name>.html (un archivo, funciona offline, seguro para enviar por correo electrónico), la profundidad de revisión utilizada y la tabla de hallazgos combinada con lo que se corrigió. Menciona: n abre el cajón de notación, las derivaciones avanzan con "Next step", los chips enlazan a enlaces permanentes de GitHub en el commit construido cuando el remoto está en GitHub. Si el repositorio tiene un vault, ofrece colocar una copia del HTML dentro, donde viven los explicadores anteriores del autor. Haz la pregunta de marca de agua de d3-scientific-wording (Paso 5) una vez; si es sí, limpia explainer/sections/*.html (nunca el archivo compilado, que incrusta MathJax y fuentes) y recompila. Ofrece hacer commit del contenido modificado (explainer/).

Notas finales

• El explicador se envía a coautores y asesores que no ejecutan el repositorio. El archivo HTML único funciona desconectado (MathJax y las fuentes se incrustan en la compilación). Cualquier persona puede abrirlo en un navegador.
• El contenido se escribe para el grupo de autores, no para revisores externos ni para un público amplio. El tono es el de una conversación entre colegas que conocen los antecedentes pero necesitan claridad sobre la idea central y sus consecuencias. Las suposiciones, las dudas y las preguntas abiertas tienen su lugar. Las interpretaciones están marcadas.
• La compilación verifica que cada chip apunte a una fuente existente. Un chip fallido significa que entendiste mal o que la fuente se movió. Corrige la afirmación, no elimines el chip.