LRU · Flujo de documentación canónica (markdown → HTML)

Fichero: lru_docs_workflow.md
Creado: 2026-04-18T09:06:06 GMT · sesión s55
Autor: Manuel + Claude Opus 4.7
Tipo: documento vivo — sin sufijo de sesión, se revisa cuando el flujo evolucione

Para qué existe este documento

Desde s55, los documentos acumulativos del proyecto se mantienen en markdown como fuente de edición y se publican como HTML canónico en el servidor, generados automáticamente con un script reutilizable. Este documento explica el flujo para que toda sesión futura lo siga sin improvisar.

Si esto no existe, cada Claude inventará un flujo distinto, editará HTML a mano, romperá la coherencia visual, y el patrón "se reinventan ruedas peor" (patrón 5 de COLLABORATION_NOTES) volverá a activarse.

Principio

El markdown es la fuente de verdad. El HTML se genera, no se edita.

Consecuencias prácticas:

Los documentos acumulativos (mapa, tech debt, misión, estado documental) se editan siempre en .md.
El .html se regenera con un script cada vez que cambia el .md.
Editar el .html directamente rompe el flujo — la próxima regeneración lo sobrescribe.
Si hay conflicto entre .md y .html, gana siempre el .md.

Ficheros del flujo

Generador

lru_md_to_html.py — script Python reutilizable. Contiene:
- El design system completo del proyecto (extraído del consolidated s53)
- Conversión markdown → HTML con todas las extensiones necesarias (tablas, código, listas, tachados, notas al pie)
- Soporte para metadatos del blockquote inicial (patrón LRU)
- Preprocesado de patrones específicos del proyecto (<del>tachado</del> → <del>)

Ubicación sugerida en el repo: raíz de public/docs-app/v1/doc/ o en un directorio tools/ separado si se prefiere.

Dependencia única

pip install markdown --break-system-packages

Sin dependencias de Node, sin toolchains adicionales. Python 3 puro.

Uso

Regenerar un solo documento

python3 lru_md_to_html.py LRU_MISION.md

El HTML sale al directorio actual.

Regenerar varios con directorio de salida

python3 lru_md_to_html.py \
  LRU_MISION.md \
  LRU_ARCHITECTURE_MAP_s55.md \
  LRU_TECH_DEBT_s55.md \
  lru_docs_status_s55.md \
  --output-dir public/docs-app/v1/doc/

Verbose para ver el detalle

python3 lru_md_to_html.py *.md --output-dir ./html --verbose

Qué documentos siguen este flujo

A 18 abril 2026 (cierre s55), los documentos con versión canónica HTML generada:

Markdown (fuente)	HTML (servidor)	Tipo
`LRU_MISION.md`	`LRU_MISION.html`	Documento vivo
`LRU_ARCHITECTURE_MAP_s55.md`	`LRU_ARCHITECTURE_MAP_s55.html`	Acumulativo con sufijo de sesión
`LRU_TECH_DEBT_s55.md`	`LRU_TECH_DEBT_s55.html`	Acumulativo con sufijo de sesión
`lru_docs_status_s55.md`	`lru_docs_status_s55.html`	Acumulativo con sufijo de sesión

Documentos que se quedan en markdown (no se convierten) hoy por hoy:

lru_debug1_analysis_s55.md — será reemplazado por documento arquitectural definitivo tras sesión dedicada, no tiene sentido convertir ahora.
lru_docs_synthesis_s55_bloques_a_b_c.md — cumplió su función; el mapa y tech debt recogen lo esencial. Queda como referencia textual.
lru_handoff_s55_s56.md — documento efímero, se consume en s56.
COLLABORATION_NOTES.md — convención del proyecto mantenerlo en markdown (editable fácilmente).

Criterio para decidir si un documento se convierte

Se convierte a HTML canónico si cumple todos estos criterios:

Es acumulativo — crece con cada sesión o es documento vivo
Se consulta frecuentemente en contexto arquitectural — decisiones de implementación lo tienen que mirar
Tiene relevancia duradera — no se va a descartar en próximas sesiones

Documentos efímeros (handoffs, síntesis de una sesión, memorias) se quedan en markdown.

Flujo completo de una edición

Abrir el .md con un editor (VS Code, cualquiera)
Editar el contenido
Regenerar el HTML con el script:
bash python3 lru_md_to_html.py LRU_TECH_DEBT_s55.md --output-dir public/docs-app/v1/doc/
Verificar abriendo el HTML en navegador
Commit ambos ficheros al repo si aplica (el .md como fuente, el .html como build output)

Qué pasa si el design system evoluciona

Si el consolidated futuro (v2) introduce variaciones visuales:

Actualizar la constante LRU_DESIGN_SYSTEM_CSS en lru_md_to_html.py
Regenerar todos los HTML afectados
Commit del script + todos los HTML regenerados en un solo cambio coherente

De este modo, una sola edición del script actualiza toda la documentación canónica de una vez.

Qué hacer en s56 y siguientes

Al empezar sesión: si vas a tocar alguno de los documentos acumulativos:
- Edita el .md
- Regenera el .html con el script
- Nunca edites el .html directamente

Si produces nuevo documento acumulativo: aplica el mismo flujo. Actualiza la tabla "Qué documentos siguen este flujo" de este documento al final de la sesión.

Si el flujo te parece mejorable: propón mejoras aquí, no cambies el script sin razón. La estabilidad del flujo es más valiosa que su perfección.

Por qué este modelo y no otro

¿Por qué no editar HTML directamente?

HTML es inviable para edición humana de texto largo
Un error de tag rompe el render sin aviso
Los diffs en git son ilegibles
Las revisiones son imposibles

¿Por qué no solo markdown?

El servidor sirve HTML nativamente con el design system aplicado
Navegación desde index.html sin conversores en tiempo real
Consistencia visual con el resto de documentación del proyecto
Posibilidad de incrustar el HTML en otras aplicaciones web

¿Por qué no Markdown con un procesador en el cliente?

Añade dependencia JS cargada en cada visita
El design system del proyecto usa CSS específico que no se integra natural con librerías JS de markdown
Generación estática es más rápida y más robusta

Registro de evolución

Fecha	Sesión	Cambio
2026-04-18	s55	Flujo establecido. Generador Python creado. 4 documentos convertidos. Documento creado.

LRU Platform · Flujo documentación canónica · documento vivo · 2026-04-18

Generado desde lru_docs_workflow.md · 2026-04-18 09:06:58 UTC · LRU Platform