¿Qué hace research-log?
Documenta investigaciones de la forma en que los ingenieros las relatan después: una historia de mediciones, una especificación lo suficientemente precisa como para reimplementarla a partir de ella, un registro de verificación con números, y una lista honesta de lo que aún se desconoce, todo entregado como un único archivo HTML autónomo (CSS e imágenes incrustadas, sin recursos externos).
El compromiso central: toda afirmación está respaldada por una medición, marcada como no probada o listada como abierta. La frase guía, si es que la necesitas: leer los artefactos te dice lo que alguien escribió; solo el sistema real te dice lo que significa.
Flujo de trabajo
1. Inventariar primero la evidencia
Recopila, antes de escribir nada, a partir de la conversación, el repositorio, los registros y el usuario:
- la cronología: fechas, qué se intentó, qué falló, qué sorprendió
- cada medición con números exactos y cómo se obtuvo
- ejecuciones de verificación: qué se comparó con qué, y las cifras de error
- las herramientas, rutas de archivos y comandos que alguien necesita para repetir el trabajo
- preguntas no resueltas e hipótesis puras
No inventes mediciones, fechas ni números. Si falta un número, pregúntalo o márcalo como ABIERTO. Un informe con datos inventados es peor que ningún informe: los vacíos en el registro son parte del registro.
2. Aprende las convenciones
Lee references/style-guide.md antes de escribir: el estilo vive en sus detalles (leyendas que prueban un punto, fracasos que se mantienen en la narrativa, números exactos, nada de marketing). Lee references/content-format.md cuando estés listo para escribir el módulo de contenido.
3. Elige el esqueleto
Seis secciones principales, numeradas, en este orden. Omite una solo por una razón justificada; inserta secciones de estudio de caso entre la especificación y las herramientas cuando haya un arco de «construcción de la cosa real».
| # | sección | debe contener |
|---|---|---|
| 1 | La historia | línea de tiempo día por día; cada paso atribuido a una medición; se incluyen callejones sin salida y sorpresas |
| 2 | Método | una frase de epistemología + la tabla: artefacto de prueba → pregunta → respuesta |
| 3+ | La especificación | tablas de byte/protocolo/formato lo suficientemente precisas como para reimplementar a partir de ellas, con etiquetas de confianza; las matemáticas como bloques de código |
| −2 | Herramientas y cómo hacerlo | comandos y rutas reales que funcionan cuando se copian textualmente |
| −1 | Registro de verificación | cada ejecución de medición con errores cuantitativos + un aviso de Conclusión |
| −0 | Preguntas abiertas | incógnitas honestas, cada una etiquetada como ABIERTA o HIPÓTESIS |
4. Escribe y construye
Escribe el contenido como un módulo de Python que define DOC (formato en references/content-format.md), mantenlo en el proyecto para que el documento pueda regenerarse, luego:
python3 <directorio-del-skill>/scripts/build_doc.py content.py out.html
Abre la salida y verifica que se renderice antes de mostrarla al usuario.
5. Autoevaluación
- cada afirmación factual lleva una etiqueta o está en el registro de verificación
- la historia incluye al menos una sorpresa, fallo o corrección; si el trabajo no tuvo ninguna, dilo claramente en lugar de inventar dramatismo
- los números son exactos y llevan unidades (0,445 s, no «rápido»; 64.779 píxeles, no «muchos»)
- cada leyenda de figura indica lo que la imagen prueba, no lo que muestra
- los comandos de «cómo hacerlo» se ejecutaron realmente, o están claramente etiquetados como no probados
- existen preguntas abiertas (siempre hay preguntas abiertas)
- la conclusión es una frase que alguien podría repetir de memoria
Las etiquetas
Cuatro etiquetas de confianza, colocadas en línea al final de la afirmación que califican:
- HW (verde) — medido en el sistema real bajo prueba. Para trabajos que no son con dispositivos, esto sigue aplicándose: medido en una ejecución en vivo, en el banco de pruebas, en producción.
- FILE (azul) — verdadero en todos los artefactos examinados (archivos, capturas, registros).
- HYP (púrpura) — consistente con toda la evidencia, pero no probado.
- OPEN (gris) — desconocido; no hay evidencia en ningún sentido.
Los hechos llevan etiquetas; los comentarios no. Si el dominio tiene mejores nombres para estas, renómbralas una vez al principio del documento y úsalas de manera consistente, pero mantén exactamente esta división de cuatro niveles.
Voz
Colega ingeniero, primera persona del plural, cero marketing. Números exactos con unidades. Frases cortas. Humor seco y escaso. Los fallos y correcciones pertenecen a la historia, no a una nota al pie. Los colegas se acreditan por su función («un colega entregó dos secuencias PNG…»).
Origen
Destilado del registro de investigación del DVE de TriCaster (waldobjekt.org, 1–3 de noviembre de 2026, escrito con Claude): el documento original incluye su propio build_doc.py; este skill generaliza esa configuración.