coread-explainer — 共読のための図解(監査つき)

¿Qué hace coread-explainer — 共読のための図解(監査つき)?

Esta habilidad consta de dos capas. El dibujo usa el kit de anatomy (cámara isométrica, sombreado de cuatro niveles, tarjeta de marco, componentes). El contenido de esta habilidad es la disciplina y el mecanismo sobre ese dibujo: leer solo datos congelados, volver a contar los números, mostrar las limitaciones en pantalla completa, llevar un libro mayor de lo que se puede / no se puede decir, y convertir las preguntas que surgen de la figura en tarjetas para responder. La figura es la superficie para "alinear la comprensión humana con la lectura de la IA", no un adorno. Por lo tanto, si ni siquiera un solo número no puede rastrearse hasta su origen, la credibilidad de toda la figura se resiente.

El primer ejemplo de referencia son las entradas de figuras con múltiples versiones (v1 a v5). La entrada de ejemplo se puede obtener a través del DOI de la galería (10.5281/zenodo.23992312 · DOI conceptual de todas las versiones). Si tienes dudas, lee sus NOTAS, RECLAMACIONES y LÉAME.

0. Decidir antes de empezar (escribir en el BRIEF)

Cada solicitud de figura se reduce a un BRIEF (pliego de condiciones) antes de crearla. Sin un BRIEF, quien la crea leerá fuera de los materiales, colocará los números a mano y decidirá su propio criterio de evaluación. Lo que se debe escribir en el BRIEF:

1. Texto literal de la solicitud (las palabras de la persona que solicita, tal cual, con la fecha).
2. Destinatarios y criterios de evaluación final (por defecto son tres. Si los destinatarios son diferentes, sustitúyelos):
   • E1 editor: La figura y el texto son fieles al artículo (o informe) y no afirman nada que el artículo no afirme. Calidad suficiente para ser publicada como figura o suplemento del artículo.
   • E2 creador de video: Solo con la captura de pantalla 1920×1080 y el guion, se puede crear una escena de 1 a 2 minutos. El núcleo es visible en los primeros 10 segundos.
   • E4 "Esta lectura proviene de este instrumento": El control positivo, la puerta (determinación de elegibilidad), el cambio de bandas o condiciones que alteran la lectura, todo debe ser visible como una cadena de evidencia sobre la captura de pantalla.
   • Si se cambian los destinatarios, también se deben escribir las pruebas de aceptación medidas con ese destinatario (por ejemplo, para estudiantes de una clase, 3 preguntas que deben responder después de ver la figura, y el criterio para una respuesta correcta). Simplemente dejar los nombres E1 / E2 / E4 no sirve como criterio para aprobar una figura dirigida a estudiantes.
3. Lista de materiales (rutas absolutas · solo leer estos) y lo que NO se lee (carpetas de otros creadores, juicios, memoria).
4. Valores de verificación (algunos números que la capa de ejecución lee de los datos). Si no coinciden, se escribe que los datos son correctos.
5. Ubicación (entry_<tag>_vN/ · no sobrescribir la carpeta de la versión anterior) y borrador (subdirectorio separado por creador).
6. Límite de tiempo (en minutos) y lo que se devuelve (≤ 10 líneas: archivos · número de estados · capturas de pantalla · resultados de verificación · el punto del que se está menos seguro).

→ La plantilla está en references/brief-template.md.

1. Contrato de datos (data contract)

• Solo se leen las salidas congeladas de las tarjetas (JSON, npz, PNG de figuras). Tarjeta = PREREG (pregunta · universo · controles · criterio de decisión · lo que no se afirma) + script + salida (procedencia = commit · dirty · md5). No se incluyen en la figura números de fuera de la tarjeta.
• No se importa ni ejecuta el script del experimento (un script de agregación sin protección en main puede, al ser importado, sobrescribir los resultados congelados). Solo se leen los archivos de datos.
• Los números los obtiene el script a partir de los datos. No se copian manualmente en HTML o guiones. Los números obtenidos se vuelven a contar por dos o más rutas independientes (por ejemplo: aserciones en Python del pack / JS de la página / lado del kernel / ancla de check_claims.py = archivo, clave y valor esperado). Si discrepan con los valores de verificación, se informa al solicitante de que los datos son correctos.
• Vallas para valores truncados: Los rangos truncados por el límite superior (por ejemplo, por debajo del lugar 1000 = 1001) se dibujan con niebla · color uniforme, y no se dibujan ni se dice "hundido" o "suprimido". El orden de truncamiento (truncar antes de la mediana, o mediana antes de truncar) se alinea con el texto de la tarjeta y la implementación. Si hay discrepancia en la mediana con un número par de elementos, se revela.
• Los valores de bandas o condiciones no elegibles solo se muestran como un lado de la comparación, con una tarjeta que diga "no ha pasado la auditoría". No se dibuja null como "no existe".
• Las filas provenientes de una misma familia (misma semilla, mismo prompt) no se cuentan de forma independiente (se especifica cómo se cuentan, por ejemplo, "3 escenas diferentes").
• La lectura del RESULTADO (L3) no son datos. Antes de trasladar una frase del RESULTADO a la figura, se verifica si esa frase se sostiene con los números de los datos. Hay ejemplos de confundir una afirmación sobre proporciones con una sobre cantidades (por ejemplo, "la mayoría de las posiciones superiores son avances y ecos" = correcto en proporción por posición, pero en cantidad la línea base ocupaba el 80% de las posiciones). Si no se sostiene, no se traslada a la figura, se pasa a "no se puede decir" en el libro mayor y se solicita una corrección al lado del RESULTADO.
• Los archivos que están en crecimiento se entregan como una copia congelada (logs, registros diarios): se escribe en el BRIEF el rango de líneas y el md5, y quien crea la figura solo lee ese rango. Esto evita que los registros añadidos posteriormente (por ejemplo, respuestas de evaluación) se mezclen con los materiales.

→ Los detalles y las trampas están en references/data-contract.md.

2. Lo que se crea (una carpeta de entrada)

entry_<tag>_vN/
  build.mjs            Construye el ESM / CSS de la página y el widget a partir del kit (no modificar el HTML manualmente)
  pack_*.py            Datos → paquete de la figura (primera ruta de verificación con aserciones)
  data.mjs / live.js   Máquina de estados de la página · dibujo (segunda ruta de verificación)
  i18n.js              Textos en ja / en
  *_widget.py/.js/.css anywidget (traits: state · row · t · layer · band · lang · theme y otros)
  demo_marimo.py  demo_jupyter.ipynb
  check_claims.py  make_check.py  run_*.sh   Pruebas (§5)
  captures/            Capturas de pantalla (§6)
  CLAIMS.md  NOTES.md  README.md  SCRIPT_yukkuri.md
  (Las capas internas son archivos separados: *_layer.js / *.css / README_internal.md — §8)

• Capítulos y estados: La figura recorre los estados (0, 1, 2 …) y se agrupan en capítulos (por ejemplo: escena → auditoría → escena del tema → una ronda de co-lectura → libro mayor). Sobre la secuencia de números de estado se colocan botones de capítulo (al pulsarlos, se va al primer estado del capítulo). Los botones de capítulo y estado se colocan por encima de los encabezados (en la parte superior de la página) (.sh-nav · en la página, sticky para que permanezcan en la parte superior de la pantalla): si se colocan debajo, la longitud del texto del encabezado hace que los botones se muevan arriba y abajo para cada estado, y se pierden después de pulsarlos (solicitante, noche del 10-28: "Al pulsar el botón, se pierde debido a la diferencia de altura de la página; por favor, colócalos en la parte superior, donde no haya movimiento vertical" · antes de la corrección, el movimiento era de más de 900 px según el estado). Se incluye en las pruebas que "el borde superior de la banda es el mismo para todos los estados". Si se renumeran los estados, se genera una lista de encabezados (número de estado → encabezado) y se verifica manualmente (el doble desplazamiento del script de renumeración ocurrió realmente).
• El widget no se envuelve en un iframe. Las operaciones sobre la figura llegan a Python, y Python puede escribir el estado (bidireccional). Funciona tanto en marimo como en JupyterLab.
• La página tiene 4 versiones (oscuro / claro × ja / en) generadas a partir de la construcción.

→ La plantilla de implementación está en references/implementation.md (un esqueleto basado en la entrada de ejemplo). La plantilla mínima está en assets/ (un esqueleto que completa la construcción, las pruebas y las capturas de pantalla con datos sintéticos: config.json es el único lugar para los números de estado, capítulo y marco / run_checks.sh / list_headings.py / evidencia de funcionamiento en _smoke/). Las nuevas figuras comienzan copiando desde aquí.

3. Disciplina del lenguaje (libro mayor: se puede decir / lectura / no se puede decir)

El libro mayor se coloca en el último capítulo de la figura, y cada línea lleva su origen (archivo y clave):

• Se puede decir (L1): Copia del valor del dato · criterio de decisión congelado.
• Lectura (L3): Se especifica quién lee (capa de ejecución / quien crea la figura), y se etiqueta con "la aceptación o el rechazo corresponde al humano". Las frases que se espera que el solicitante sustituya se etiquetan como tales.
• No se puede decir: Se afirma explícitamente con una oración declarativa ("No se dice que…"). No se termina con una nota pequeña o un "quizás". Al menos: mecanismo / identificación (cuando el fallo se ha dejado como yuxtaposición, no se llama igual) / juicio de cantidad (cuando la diferencia es menor que la banda de error) / lectura fuera del rango de validez del instrumento / lado no leído (por ejemplo, el lado del prompt) / "solo" a partir de un ejemplo / contar líneas no independientes como independientes.

Palabras que no se usan en el texto ni en el guion: "el modelo pensó · dudó · se dio cuenta · sabía · en realidad sabía", "se vio la mente de la IA", "descubrir la mentira" y exageraciones similares. La clasificación de una lente es la lectura de la lente, no un mapa del interior del modelo; se escribe así en la figura.

Las etiquetas de limitación se muestran en todas las pantallas del capítulo (una línea debajo del marco + una etiqueta de identidad en la esquina superior derecha): rango de validez · solo descriptivo · no se identifica · lado no leído · n. Las limitaciones que no aparecen en la captura de pantalla son como si no existieran. Pero antes de pegar la limitación, se verifica si realmente se aplica a los datos de esa pantalla. No se copian los ejemplos de redacción (references/wording.md) en todos los capítulos sin más. Por ejemplo: "todas las posiciones están fuera del rango de ajuste del instrumento" se verifica por fila y posición (en el ejemplo, algunas filas bajo una condición estaban fuera, pero otras filas bajo otra condición tenían un prompt más corto y estaban dentro). Si el rango aplicable se divide dentro del capítulo, las etiquetas se dividen por fila.

→ Los ejemplos de redacción y la lista de palabras prohibidas están en references/wording.md.

4. Patrones de presentación (los que funcionaron en v1 a v5)

• La entrada es una escena: El primer capítulo muestra "qué es el momento que ocurrió" en una sola imagen (por ejemplo: la palabra intermedia flota sobre el prompt antes de escribir la respuesta · la placa de la respuesta está vacía). La auditoría de los números viene después.
• Tres ejes del espacio 3D: Horizontal = posición (tokens que se van escribiendo) · Vertical = capa · Profundidad = clasificación del instrumento (primero = 1 · logarítmica · más allá del límite superior = niebla). Las bandas de control son placas gruesas; fuera de las bandas es gris, "fuera del control · referencia".
• Comparar éxito y fracaso: Colocar dos espacios 3D en una misma proyección · una misma cámara · una escala común; si uno gira, ambos giran. El video es izquierda/derecha; escritorio / teléfono es apilado verticalmente (para mantener el tamaño mínimo de letra de las tarjetas).
• Declarar cómo se alinean: Para dos filas con diferentes salidas, se especifica dónde se alinearon (punto de divergencia / palabra clave / inicio de columna), y si la distancia desde el punto de alineación hasta la palabra clave es diferente, se escribe "+1 token / +3 token". Se muestran vistas alineadas por distancia (small multiples alineados por la posición k de la palabra clave).
• Dibujar las partes de longitud 0 también con marcos: Las partes que solo existen en un lado (por ejemplo, columna de pensamiento tokens / 0 tokens) se representan con marcos del mismo ancho en ambos lados; uno de ellos es un marco vacío con línea de puntos. Si solo se deja espacio en blanco, parece un error de dibujo y se critica.
• Avances y ecos: Si el instrumento coloca en las posiciones superiores "la palabra que está a punto de escribir" o "la palabra que acaba de escribir", esas posiciones (F / E) se marcan con un símbolo diferente y se muestran por separado de las posiciones tranquilas.
• No rellenar lo que no está en los datos: Si los datos solo son agregados y no tienen una posición por fila, la escena de entrada se etiqueta como "diagrama esquemático (no es una fila real)". No se dibujan estados intermedios no registrados (por ejemplo, entre 3 unidades → 1 unidad, intercalar 2 unidades · el orden en que desaparecen una a una). Los momentos fuera del intervalo de registro (por ejemplo, cada 2 minutos) se escriben como "en algún momento entre estos dos" con una banda de tiempo.
• Los nombres se definen en un solo lugar: Los nombres de posiciones, filas y capas (por ejemplo, "punto de divergencia" o "posición alineada") se colocan en un solo lugar (helper o config), y todas las pantallas llaman a la misma cosa con el mismo nombre. Se añade una prueba que escanea si quedan nombres antiguos (§5).
• Cada color tiene un solo significado: Se mantienen los colores que ya tienen un significado (por ejemplo, naranja = par He/Hi · azul = par apex) y no se añaden nuevos colores. Si se añade color solo para decoración no basada en datos (por ejemplo, metáfora de capa interna), se verifica con el validador de dataviz que el ΔE normal ≥ 15 y el ΔE CVD ≥ 8 en ambas superficies (oscuro/claro) respecto a los colores existentes. No se utilizan personajes, imágenes ni fuentes externas de terceros.

5. Pruebas (pasar todas antes de capturar)

• Consola limpia (4 versiones de página · escritorio · teléfono · video · movimiento reducido · marimo · JupyterLab). Las advertencias de extensiones no relacionadas con la figura se registran y se distinguen.
• Robustez: Excepciones 0 para todas las combinaciones de estado × fila × algunas capas.
• Verificación numérica: Todos los anclajes de check_claims.py (archivo · clave · valor esperado) coinciden · 0 faltantes. Valor de verificación N / N.
• Botones de capítulo: Al hacer clic real, se llega al primer estado de cada capítulo · la apariencia seleccionada, hash y etiqueta (ja/en) coinciden.
• Tamaño de letra: Se mide el px mínimo de las tarjetas para cada marco de captura (referencia: video ≥ 10 px · escritorio ≥ 10 px · teléfono ≥ 9.5 px). Las tarjetas ilegibles son como si no existieran.
• Desbordamiento: 0 caracteres fuera del viewBox.
• Vallas de publicación: 0 ocurrencias de palabras internas (§8) en los archivos principales (contar con grep).
• Escaneo de nombres: Se escanea el texto de todas las páginas (todos los estados × ja/en) y se detectan 0 ocurrencias de nombres antiguos o contextos prohibidos. También se realiza un control positivo del propio escaneo (se debe poder detectar texto antiguo mezclado en una página de prueba).
• Nota sobre herramientas: El px mínimo de las tarjetas en teléfono solo alcanza 9.5 px después de reducir el viewBox para agrandar la letra y cambiar el texto de las cuatro esquinas del kit a una columna vertical (el valor inicial de la plantilla era 2.7 px). ?video=1 oculta los botones de capítulo, por lo que la prueba de clic se realiza en escritorio y teléfono.

→ references/checks-and-captures.md.

6. Captura de pantalla y guion

• 1920 × 1080 para cada estado (para video · exactamente ese tamaño) + escritorio (oscuro/claro) + teléfono. Los estados que muestran un instante se capturan como dos imágenes consecutivas (por ejemplo, posición 24 → 25).
• SCRIPT_yukkuri.md: Diálogo (A = oyente / B = explicador) de ≤ 150 segundos · cada línea tiene la señal del estado que se muestra · los primeros 10 segundos son la escena. No se usan nombres ni imágenes de personajes reales.

7. Una ronda de co-lectura (el uso principal de esta figura)

Cuando una persona que ve la figura hace una pregunta (por ejemplo: "¿de dónde surge He?"), se convierte en una tarjeta y se responde. Procedimiento: 0. Verificar las palabras de la pregunta: Se comprueba si la posición, fila o palabra a la que se refiere la pregunta se determina de forma única dentro de la figura. Si el nombre fluctúa dentro de la figura (por ejemplo, la misma posición se llama "punto de divergencia" en una pantalla y "un paso antes del punto de divergencia" en otra), antes de leer los números, se confirma con la persona que hizo la pregunta en una sola pregunta, y también se corrige la fluctuación de nombres en la figura.

1. Enumerar candidatos (lectura · L3): Dos o tres explicaciones que podrían responder a la pregunta. A cada una se le asignan tres marcas: (a) Depende o no depende del instrumento (lente) / (b) Si esa cantidad está en persist (datos guardados) · se necesita un forward nuevo · se necesita una nueva generación ("no está en persist" no significa "la cantidad no existe" — por ejemplo, la clasificación de la salida del modelo en sí existe en cada posición, pero solo se guardó la clasificación del token escrito) / (c) Si toca las vallas del artículo (por ejemplo, no conectar predicados a capas fuera de la banda de control). El orden es: primero los candidatos que "no dependen de la lente · están en persist", luego los que necesitan un forward, y después los que dependen de la lente. Los candidatos que tocan las vallas se descartan.
2. Congelar la tarjeta primero: PREREG (pregunta · universo · controles = incluyendo control positivo · palabras del método de lectura · lo que no se afirma · divulgación de lo visto previamente) y script se colocan en un solo commit, y --fire solo se ejecuta cuando no está sucio. Congelar antes de ver los valores.
3. Leer → RESULTADO: Los números son copias de la salida (L1) · la lectura es L3 · lo que no se afirma permanece como en el PREREG.
4. Detenerse si el control falla: Sin escribir los datos de la figura, se detiene. Se diagnostica la causa solo en el lado del texto, y se vuelve a congelar la versión corregida como una nueva tarjeta (no se cambia la definición de la tarjeta después de que se haya ejecutado). Ejemplo: la decodificación de caracteres por token se distorsionó en la división de un carácter multibyte, convirtiéndose en U+FFFD, y la posición y el texto se desalinearon → el control C2 lo detectó → nueva tarjeta que maneja la correspondencia por byte. Se registra como un ejemplo real de que la lectura de la IA también necesita controles.
5. Devolver a la figura como un estado: "De la figura surge una pregunta, se responde con una tarjeta" = ver la figura → pregunta humana → candidatos de la IA → congelar la tarjeta y leer → respuesta y lo que no se puede decir → siguiente pregunta.

→ references/coread-loop.md (plantilla de tarjeta · concepto de control).

8. Capas internas (metáforas · jerga interna)

Cuando se desea incluir metáforas internas del laboratorio (por ejemplo, nombres internos, mascotas) en la figura, se convierten en una capa oculta: se colocan en archivos separados (*_layer.js / *.css / README_internal.md), y el cuerpo principal solo hace "si existe, lo lee; si no existe, no hace nada". La activación / desactivación se realiza mediante un comando oculto (secuencia de teclas) + un flag en la URL + un trait del widget. Por defecto, desactivado · solo en páginas en japonés · no hace nada en páginas en inglés. Cuando la capa está activada, aparece en la esquina superior derecha "capa interna · no mostrar externamente". Se incluye en las pruebas que el archivo principal tenga 0 ocurrencias de jerga interna (para que la entrada no quede fuera del conjunto de publicación). Los dibujos de las metáforas se crean por cuenta propia, y dentro de la capa también se afirma explícitamente "no se puede decir" para que la metáfora no se interprete como una afirmación sobre el mecanismo.

9. Revisión y versionado

• Cada versión tiene su propia ubicación (_v1…_vN), y no se sobrescribe la versión anterior. Las correcciones menores se registran como vN.1, vN.2 … en las NOTAS, indicando "qué se corrigió · quién lo señaló".
• La revisión la realiza un lector en frío de un modelo de familia diferente al del creador, al que solo se le entregan el archivo de criterios de evaluación, las capturas de pantalla y los archivos CLAIMS / NOTES / README (no se muestran los juicios entre sí · no se permite adivinar quién es el creador). Los criterios son E1 / E2 / E4 (+ E3 como referencia). La plantilla de criterios está en references/judging.md.

10. Publicación (para acompañar a un artículo)

• La página funcional se muestra en GitHub Pages (sitio estático), y la versión del mismo repositorio se congela con un DOI en Zenodo (Zenodo no renderiza HTML, pero si se descarga el conjunto, funciona con file://). En el artículo se escriben ambos.
• Se retiran las capas internas (§8) del conjunto de publicación. Se conserva la atribución MIT de Anatomy (Copyright (c) 2026 Ryan) en el LÉAME y en la parte inferior de la página.
• Incluir este mismo SKILL.md en el conjunto: Aunque no sea posible una reproducción completa, se puede mostrar el procedimiento (prompt) con el que se creó la figura.
• md5 en el MANIFIESTO. → references/publishing.md.