# CODEX.md

Guia maestra para producir resúmenes académicos de alta calidad en HTML/PDF con coherencia conceptual, densidad útil y gráficos claros.

Esta guía está diseñada para cualquier materia:
- economía
- física
- historia
- biología
- derecho
- ingeniería
- filosofía
- otras

Objetivo: que cualquier IA pueda replicar un estándar profesional de resumen de estudio, no solo “texto lindo”.

## 1) Principios de diseño (no negociables)

1. Claridad causal
- Cada afirmación importante debe responder: qué cambia, por qué cambia y qué consecuencia produce.
- Evitar listas de definiciones sin mecanismo.

2. Legibilidad real para estudiar
- El documento debe poder leerse en bloques de 15-25 minutos.
- Los títulos deben guiar la estrategia de estudio, no solo “decorar”.

3. Densidad informativa sana
- Evitar páginas vacías o con 2 líneas.
- Evitar “paredes de texto” sin respiración visual.

4. Coherencia visual
- Mismo sistema de colores, etiquetas y jerarquía tipográfica en todo el documento.
- En gráficos, usar siempre convenciones constantes (ejes, colores, flechas, leyendas).

5. Verificación pre y post PDF
- Revisar HTML antes de exportar.
- Revisar PDF final (paginado, cortes, legibilidad, textos residuales tipo `file://`).

## 2) Flujo de trabajo general (end-to-end)

1. Ingesta de fuentes
- Reunir transcripción (`.txt`), material bibliográfico (`.pdf`) y guía de cátedra si existe.
- Detectar ruido de transcripción: muletillas, repetición, errores de OCR.

2. Extracción semántica
- Separar: conceptos núcleo, definiciones, procedimientos, ejemplos de clase, errores típicos de examen.
- Marcar explícitamente qué partes son “base” y cuáles son “expansión didáctica”.

3. Diseño de estructura
- Construir índice con progresión lógica (de fundamentos a aplicación).
- Incluir sí o sí: casos resueltos, checklist, autoevaluación.

4. Redacción por capas
- Capa 1: idea central de sección en 1-2 párrafos.
- Capa 2: tabla o esquema operativo.
- Capa 3: caja de “importante” o “error frecuente”.
- Capa 4: caso aplicado.

5. Maquetación HTML
- Usar componentes consistentes: portada, secciones, tablas, cajas, gráficos SVG, banco de casos.
- Preparar para impresión A4 desde el inicio.

6. Exportación PDF
- Exportar con motor headless estable (Chromium recomendado).
- Desactivar headers/footers automáticos del navegador.

7. QA final
- Verificar páginas “casi vacías”.
- Verificar cortes feos (tabla partida, título huérfano, caja cortada).
- Verificar coherencia de gráficos y legibilidad de flechas/etiquetas.

## 3) Estructura recomendada del resumen (plantilla universal)

1. Portada
- Materia + clase + tema central.
- Objetivo de estudio de esa clase.
- Mapa rápido (ruta de lectura en una línea).

2. Índice
- 6 a 12 bloques como máximo por clase regular.
- Nombres de sección orientados a acción.

3. Desarrollo conceptual
- Definiciones esenciales.
- Mecanismos principales.
- Tabla de términos operativos.

4. Aplicación
- Casos simples.
- Casos combinados o ambiguos.
- Errores frecuentes.

5. Entrenamiento examen
- Simulación de parcial (preguntas).
- Respuestas modelo cortas.
- Preguntas de desarrollo.

6. Cierre
- Checklist final.
- Tarjetas de repaso.
- Mini glosario.

## 4) Reglas de redacción (para cualquier disciplina)

1. Escribir en modo operativo
- En vez de “la elasticidad es importante”, escribir: “si |E| > 1, un aumento de precio reduce recaudación”.

2. Separar descripción de inferencia
- `Descripción`: qué se observa.
- `Inferencia`: qué significa y bajo qué condiciones.

3. Evitar ambigüedad de sujeto
- No usar “esto cambia aquello” sin especificar variable.

4. Definir límites
- Toda regla importante debe incluir cuándo no aplica.

5. Frases de cierre por sección
- Cerrar sección con una frase “si te preguntan X, responde Y con Z mecanismo”.

## 5) Componentes visuales y semánticos

### 5.1 Cajas semánticas

- `.definicion`
  - Uso: concepto técnico o regla formal.
  - Debe responder “qué es”.

- `.importante`
  - Uso: advertencia, límite, error típico.
  - Debe responder “qué no confundir”.

- `.ejemplo`
  - Uso: traducción a caso concreto.
  - Debe responder “cómo se aplica”.

### 5.2 Tablas

Usar tablas para:
- comparaciones (A vs B)
- pasos de procedimiento
- matriz de cambios

Reglas:
- encabezado corto y explícito
- 3-5 columnas máximo
- celdas con frases breves, no párrafos largos

### 5.3 Gráficos (estándar universal)

Principio: todo gráfico debe poder leerse en 10 segundos.

Checklist mínimo por gráfico:
- ejes rotulados
- elementos con nombres visibles
- leyenda de colores
- flecha/sentido de cambio claro
- caption con interpretación
- bloque “Lectura del gráfico” con mecanismo en texto

## 6) Guía técnica de gráficos por tipo de materia

### 6.1 Economía

Formato base:
- Eje vertical: precio/salario/tasa
- Eje horizontal: cantidad/trabajo/fondos
- Curva inicial: gris
- Curva nueva: color principal (rojo demanda, verde oferta)
- Flecha: azul oscuro gruesa
- Resultado: texto final con dirección de equilibrio

Lectura mínima obligatoria:
- `Curva implicada`
- `Mecanismo`
- `Resultado`

### 6.2 Física

Gráficos típicos:
- posición-tiempo, velocidad-tiempo, aceleración-tiempo
- energía potencial vs coordenada
- circuitos (I-V)

Reglas:
- incluir unidades SI en ejes
- marcar pendiente/área cuando tenga significado físico
- incluir condición inicial/final
- indicar régimen (lineal/no lineal)

### 6.3 Historia

Gráficos útiles:
- línea de tiempo con hitos
- mapa de actores (Estado, grupos, alianzas)
- matriz causa-evento-consecuencia

Reglas:
- separar causas estructurales de detonantes
- distinguir corto vs largo plazo
- marcar continuidad vs ruptura

### 6.4 Biología

Gráficos útiles:
- rutas (metabólicas, señalización)
- taxonomías jerárquicas
- tablas comparativas de procesos

Reglas:
- nombrar niveles de organización
- explicitar entrada/salida de cada proceso
- marcar regulación positiva/negativa

### 6.5 Derecho

Diagramas útiles:
- flujo procedimental
- jerarquía normativa
- mapa de requisitos y excepciones

Reglas:
- identificar fuente normativa
- separar regla general y excepción
- incluir condición de aplicación

## 7) Estándar CSS recomendado (impresión A4)

Reglas de impresión:
- `@page size: A4`
- márgenes 1.5 a 2.0 cm
- tipografía serif para cuerpo (Georgia/Times)
- tamaño base 10.8-11.2 pt

Control de cortes:
- evitar `break-inside: avoid` global indiscriminado
- aplicar `break-inside: avoid` solo en:
  - tablas
  - cajas críticas
  - tarjetas de casos

Evitar páginas en blanco:
- no forzar `page-break-before` salvo secciones pesadas (ej: banco de casos)
- si un título queda solo al final de página, ajustar bloques previos o mover sección completa

## 8) Exportación PDF robusta

Comando recomendado:

```bash
chromium \
  --headless \
  --disable-gpu \
  --no-sandbox \
  --no-pdf-header-footer \
  --print-to-pdf="salida.pdf" \
  "file:///ruta/entrada.html"
```

Notas:
- `--no-pdf-header-footer` evita contaminación con `file://` en pie.
- Si aparecen rutas en PDF, revisar opciones de impresión primero.

## 9) QA automático mínimo

Herramientas:
- `pdfinfo`: cantidad de páginas
- `pdftotext`: extracción y búsqueda de basura textual
- `rg`: detección rápida de patrones no deseados

Controles:
1. Páginas casi vacías
- detectar páginas con bajo conteo de caracteres

2. Referencias no deseadas
- buscar `file://`, `.txt`, `.pdf` si el usuario pidió ocultarlas

3. Coherencia semántica
- cada gráfico debe tener caption y lectura textual

4. Integridad visual
- no cortar tablas ni cajas
- no superponer flechas con etiquetas principales

## 10) Criterios de calidad (rúbrica 0-5)

1. Precisión conceptual
- 0: errores de concepto graves
- 5: conceptos correctos y bien delimitados

2. Coherencia causal
- 0: listado sin lógica
- 5: mecanismo explícito en cada bloque

3. Utilidad para examen
- 0: no entrenable
- 5: casos + respuestas + checklist

4. Calidad visual
- 0: ilegible o inconsistente
- 5: limpio, consistente, imprimible

5. Control técnico
- 0: PDF defectuoso
- 5: sin residuos, sin páginas vacías, sin cortes feos

## 11) Reglas para banco de casos

Cada tarjeta de caso debe contener:
- título del caso
- por qué cambia
- curva/variable implicada
- mecanismo causal
- gráfico coherente
- resultado final

No aceptar tarjetas con:
- solo flechas
- gráfico sin explicación
- explicación sin variable concreta

## 12) Reglas para materias cuantitativas

Agregar siempre:
- fórmula núcleo
- interpretación económica/física/estadística de cada término
- ejemplo numérico mínimo
- error típico de cálculo

Cuando haya derivaciones:
- no mostrar álgebra larga si no agrega aprendizaje
- priorizar: qué representa, cuándo usarla, cómo interpretar signo/magnitud

## 13) Reglas para materias cualitativas

Agregar siempre:
- periodización o estructura argumental
- actores, intereses, instituciones
- relación causa-contexto-consecuencia
- contraste entre 2 interpretaciones

Evitar:
- relato cronológico sin tesis
- opiniones sin anclaje conceptual

## 14) Estrategia anti-ruido de transcripción

Cuando la fuente es clase oral transcripta:
- limpiar muletillas y repeticiones
- preservar ejemplos de cátedra que aclaren examen
- reconstruir frases incompletas manteniendo sentido
- marcar inferencias cuando la transcripción es ambigua

## 15) Política de trazabilidad (sin contaminar el PDF)

Internamente:
- guardar scripts de generación y QA
- versionar cambios de estructura y estilo

En PDF final:
- no imprimir rutas locales
- no imprimir referencias de archivos si el usuario lo pidió
- no insertar notas técnicas irrelevantes para estudio

## 16) Plantilla de prompts para IA (genérica)

Prompt base:
- “Construye un resumen extendido de [materia/tema], orientado a examen, en formato HTML imprimible A4, con:
  - índice
  - desarrollo conceptual
  - tablas operativas
  - banco de casos con gráficos SVG claros
  - simulación de examen
  - checklist final
  - sin referencias a rutas de archivos en el PDF.”

Prompt de QA:
- “Audita este HTML/PDF buscando:
  - páginas con bajo contenido
  - títulos huérfanos
  - gráficos sin contexto
  - etiquetas ilegibles
  - texto basura (file://, rutas)
  y propone correcciones puntuales.”

## 17) Errores frecuentes de IA y correcciones

1. Error: demasiado resumen, poca utilidad
- Corrección: añadir banco de casos y respuestas modelo.

2. Error: gráficos bonitos pero ambiguos
- Corrección: incluir leyenda, curva implicada y mecanismo textual.

3. Error: demasiados saltos de página
- Corrección: reducir `page-break` forzado y reequilibrar bloques.

4. Error: repite teoría del libro sin foco de examen
- Corrección: priorizar preguntas-tipo y decisiones de resolución.

5. Error: no distingue hechos de inferencias
- Corrección: separar “dato/definición” de “interpretación/aplicación”.

## 18) Checklist final antes de entregar

Checklist editorial:
- índice consistente con secciones
- numeración correcta
- no hay contradicciones internas

Checklist visual:
- gráficos legibles al 100%
- flechas claras
- etiquetas no montadas

Checklist técnico:
- PDF abre y pagina bien
- no hay `file://`
- no hay páginas casi vacías

Checklist pedagógico:
- hay práctica de examen
- hay respuestas modelo
- hay errores frecuentes
- hay cierre operativo

## 19) Meta-estándar esperado

Un resumen de “nivel alto” no es el más largo.
Es el que logra simultáneamente:
- comprensión conceptual
- capacidad de resolver ejercicios
- lectura rápida y confiable antes del examen
- salida PDF limpia y estable

Si falta uno de esos cuatro, el resumen está incompleto.