explain-it

¿Qué hace explain-it?

Convierte el código que has investigado en un pequeño sitio HTML estático que un lector inteligente sin contexto de este repositorio pueda seguir: una página raíz que construye el modelo mental, una página por tema y un sidebar que las conecta.

El objetivo: "un lenguaje simple que no sea ni demasiado simple ni demasiado difícil." Nunca menosprecies; nunca asumas conocimiento del repositorio.

Flujo de trabajo

1. Investiga antes de explicar

Nunca expliques código que no hayas leído. Por cada tema, lee el código fuente real: las líneas modificadas, la función contenedora y al menos un llamador, para que puedas responder "¿cuándo se ejecuta este código?" con una historia real. Si una afirmación proviene de otra persona (un comentario de revisión, un issue), verifícala contra el código primero y di si no se sostiene.

2. Planifica el sitio

• Una página raíz (index.html): el primer contacto. Construye el modelo mental del sistema en ~2 minutos y enlaza a cada página de tema.
• Una página por tema (01-<slug>.html, 02-<slug>.html, …): cada una explica un cambio, error, decisión o subsistema. 3–7 páginas es el punto ideal; fusiona temas en lugar de exceder ~9.
• Un sidebar compartido en cada página que enumera todas las páginas en orden de lectura, con la página actual resaltada. Las páginas son archivos planos enlazados con <a href> relativo — el sitio debe funcionar abierto directamente desde el disco (file://), por lo que no hay enrutadores, ni paso de compilación, ni JS externo.

Pregunta al usuario dónde colocar la carpeta solo si no hay una ubicación obvia; de lo contrario, crea una carpeta con un nombre sensato junto al trabajo (por ejemplo, docs/explicadores/<tema>/) y di dónde la pusiste.

3. Escribe cada página

Sigue references/writing-guide.md para el método — léela antes de escribir tu primera página. Los puntos no negociables:

• Primer contacto primero. La página raíz introduce cada concepto del dominio que las páginas de tema necesitan, cada uno con una metáfora concreta (por ejemplo, "un release es una fotocopia; un trabajo en ejecución fija una fotocopia"). Introduce una metáfora una vez, luego reutilízala textualmente en todas partes. Nunca apiles dos metáforas para un mismo concepto.
• Fundamenta cada tema en tiempo de ejecución. Cada página de tema comienza con una historia de "¿Cuándo se ejecuta este código?": 2–4 pasos de actor (Usuario hace X → Sistema ejecuta la función Y → el pequeño trabajo dentro de ella). Nombres de funciones reales en fuente de código, junto — nunca en lugar de — la historia en lenguaje sencillo.
• Muestra el cambio como un diff. Código antiguo vs nuevo en bloques diff rojo/verde con la ruta del archivo en el encabezado, recortado al punto clave, con 1–3 comentarios en línea señalando por qué — no narrando qué.
• Cuantifica el "por qué". "Lento" está prohibido; "cientos de KB por solicitud, ~99% del tiempo para nada" es el estándar. Lo mismo para el riesgo: nombra la entrada/estado concreto y el resultado incorrecto.
• Separa errores de decisiones. Si algo es una elección de producto defendible en lugar de un defecto, preséntalo como una decisión con la compensación, no como un error.
• Termina la página raíz con un marcador: una tabla de estado de cada elemento (hecho / propuesto / aparcado) con su ubicación en el repositorio.

4. Construye el HTML

Copia references/site-template.html como punto de partida para cada página — contiene los tokens de diseño, el sidebar y un ejemplo funcional de cada componente (bloque de historia, llamada, bloque diff, tabla de estado, etiquetas). Luego:

• Mantén cada página completamente autocontenida (todo el CSS en línea en la página). El sidebar se duplica en cada página con el elemento actual marcado class="on".
• Sigue references/design-system.md para tokens y reglas de componentes. Mantén la paleta, el espaciado y la escala tipográfica tal como se dan para que los sitios de varias páginas parezcan un solo sistema. La plantilla incluye un alternador claro/oscuro y un sidebar plegable — lleva ambos a cada página en lugar de omitirlos.
• Sin dependencias externas excepto el enlace a Google Fonts ya presente en la plantilla (la pila de fuentes retrocede limpiamente sin conexión) y sin JS más allá del fragmento de alternador de tema de la plantilla.

5. Verifica antes de entregar

Abre o renderiza la página raíz y al menos una página de tema (o vuelve a leerlas) y verifica: cada enlace del sidebar resuelve, cada identificador de código mencionado en prosa existe en el repositorio con esa ortografía exacta, cada diff compila conceptualmente contra el archivo real y los estados del marcador están actualizados. Luego informa al usuario la ruta de la carpeta y abre la página raíz para él si el entorno lo permite.

Errores comunes

• Explicar desde la memoria de la conversación en lugar del código — el explicador hereda cada afirmación desactualizada. Relee la fuente.
• Deriva de la metáfora: llamarlo "fotocopia" en una página y "copia congelada" en la siguiente. Un término, en todas partes.
• Bloques diff que pegan 60 líneas textuales. Recorta al punto clave; mantén 2–4 líneas de contexto alrededor.
• Prosa que narra el diff línea por línea. El diff muestra qué; la prosa solo lleva por qué importa y cuándo se ejecuta.
• Un sidebar que solo existe en la página índice. Cada página lleva el sidebar completo.
• Lenguaje infantil ("la computadora recuerda cosas en una caja especial"). El lector es inteligente — simplemente no conoce este repositorio.