DELTA37/structured-report

Informe estructurado

Un único archivo HTML autocontenido (sin red) que permite a un lector ocupado

1. ver todo el trabajo como un mapa de tareas, con lo que le espera dentro de cada tarea,
2. abrir cualquier tarea —y cualquier etapa dentro de ella— y auditar cómo se hizo y por qué se cree cada afirmación,
3. responder las preguntas del agente allí mismo, y ver qué prompts suyos produjeron qué.

Estructura vs. contenido

• La estructura pertenece a la plantilla (assets/template.html): diseño, nombres de secciones (Problema, Tarea, Contexto, Conclusiones, Suposiciones, Resultado, No verificado, Flujo de trabajo, Necesita aprobación, Tus acciones), su orden, estados, cada icono y cada etiqueta de la interfaz. Fija, siempre en inglés. Los iconos marcan solo la estructura, nunca el contenido.
• El contenido es tuyo: el JSON, en el idioma del usuario. scripts/build.py lo valida y llena los marcadores de la plantilla. Nunca escribes HTML ni inventas secciones.

Flujo de trabajo

1. Recopila el material: mensajes, resultados de herramientas, archivos, comandos, enlaces, pruebas, mediciones, decisiones. Informa solo de lo que realmente ocurrió.
2. Divídelo en tareas (1–12): una tarea = un objetivo con su propio resultado. Conéctalas con links: depends, blocks, related.
3. Llena cada tarea siguiendo las reglas a continuación y references/schema.md.
4. Escribe el JSON — por defecto reports/<AAAA-MM-DD>-<slug>.json en el directorio de trabajo.
5. Construye: python3 <skill>/scripts/build.py <archivo>.json → <archivo>.html. Corrige cada error:; lee cada warning: y corrígelo a menos que sea genuinamente cierto.
6. Ábrelo localmente (open / xdg-open / start) y proporciona la ruta. Nunca lo subas.
7. En el chat: 2–4 líneas — el resultado principal y lo que espera al lector.

Informe vivo: sigue la sesión, recoge las respuestas

Cuando el usuario quiera mantener el informe actualizado a lo largo de la sesión (o pida un informe rastreado / vivo), vincula la sesión una vez:

python3 <skill>/scripts/track.py start reports/<archivo>.json      # crea <archivo>.journal.json

A partir de entonces, el hook UserPromptSubmit (instálalo una vez: track.py install-hook, que también añade el hook de Stop) registra cada prompt del usuario en el diario y te recuerda el número de prompt. Después de cada prompt que cambie el trabajo, actualiza el JSON y reconstruye — build.py coloca una huella digital en cada bloque (cada nodo × sección) y marca los bloques nuevos o modificados con el prompt actual. Nunca escribas las marcas tú mismo. El informe muestra un carril de Prompts; al seleccionar un prompt se resalta lo que apareció (verde) o cambió (azul) allí.

Preguntas para el lector. Pon las decisiones en approvals. Cada una es una pregunta con options — exclusivas por defecto (una respuesta) o "multi": true (cualquier opción que aplique) — tu recommend (una lista para multi), why y due. El lector siempre tiene "tu propia respuesta" como opción extra; una pregunta sin opciones se responde en texto libre. En el informe, las preguntas abiertas de una sección Necesita aprobación forman una serie, una pregunta a la vez: una opción exclusiva responde y avanza, una opción múltiple o respuesta propia se confirma con Siguiente, la serie termina con una revisión de todas las respuestas, y Enviar respuestas te las envía — no hay otra forma de enviar, y actions (pasos que toma el lector) no tienen campos de entrada. Las respuestas van a un servicio local de respuestas (127.0.0.1:47319, iniciado y mantenido actualizado por la construcción) incluso cuando el informe se abre como un archivo plano, y se almacenan en el diario como el siguiente prompt. Mientras el informe tenga preguntas abiertas, mantén un waiter ejecutándose como comando de fondo:

python3 <skill>/scripts/track.py wait reports/<archivo>.json

Cuando el lector envíe, wait imprime las respuestas y termina — esa salida vuelve a ti: trátala exactamente como el prompt del usuario y continúa; vuelve a iniciar wait si quedan preguntas. Si no hay un waiter en ejecución, el hook de Stop entrega las respuestas en cola antes de que termine tu turno, y el hook UserPromptSubmit las adjunta al siguiente mensaje del usuario — las respuestas nunca se pierden. Las preguntas respondidas se muestran como respondidas después de la siguiente construcción. --static construye un informe sin el canal de respuestas (para compartir fuera de esta máquina): las preguntas se muestran solo de lectura, sin campos de entrada.

Enlace debajo del campo de entrada. scripts/statusline.py imprime una fila de la barra de estado para el informe de la sesión: su título como un enlace en el que se puede hacer clic que abre el HTML en el navegador, y cuántas preguntas aún esperan. Úsalo como la barra de estado o añade su salida a una existente; no imprime nada para sesiones sin informe.

Cada bloque del informe tiene un botón copiar como Markdown (todo el informe, una tarjeta de tarea, un informe, una sección, un elemento individual, un paso, un prompt) — indícale al lector que lo use cuando quiera pegar algo en otro lugar.

Las reglas que hacen que el informe sea confiable

Separa cómo sabes cada cosa; nunca lo difumines.

• context — fuentes que realmente consultaste: id (C1…), title corto, una url real y una note con el hecho exacto tomado. Nunca inventes URLs. Prefiere URLs de repositorio / web: los enlaces file:// no se abren en la máquina del lector (la construcción avisa; un archivo local faltante es un error).
• inferences — conclusiones, cada una con basis (ids de contexto) y confidence. Sin basis → es una suposición.
• assumptions — tomadas como verdaderas sin verificar: why, cómo verify, risk si están equivocadas.
• unchecked — lo que no verificaste o hiciste, con why no. Los lectores confían en esto más que en cualquier otra cosa; dilo claramente. Una tarea terminada sin unchecked recibe una advertencia ([] significa "verificado todo" — solo si es cierto).
• result — lo que existe ahora, como elementos tipificados. Cada elemento verified necesita how: el comando, prueba o enlace que lo prueba — la construcción falla sin ello.
• stages — los pasos que realmente diste, 2–8 por nivel. Una etapa es el mismo tipo de nodo que una tarea: id + title obligatorios, cualquier campo de tarea permitido, sus propios stages + flow, a cualquier profundidad. En la tarjeta muestra detail (lo que hiciste), outcome (lo que salió), status, when, uses. Al hacer clic en una etapa se abre su informe con la misma estructura, así que dale contenido real a las etapas que fueron trabajo real. Los callejones sin salida también son etapas (failed / skipped).
• next steps are planned stages — cualquier cosa aún por hacer es una etapa con status: "planned", un detail (lo que se hará) y when (la condición o tiempo: "después de tu aprobación", "lunes"). Una tarea sin terminar sin ninguna etapa planificada o en progreso recibe una advertencia.
• approvals — decisiones que solo el lector puede tomar: la pregunta, why es suya, options (exclusivas, o multi: true), tu recommend (una de las opciones; una lista para multi), due. Varias preguntas relacionadas en un nodo se convierten en una serie — ordénalas según como el lector deba responderlas. Nunca pidas aprobación para algo ya hecho.
• actions — cosas que solo el lector puede hacer, con el command exacto y due cuando corresponda.
• secrets — el informe se reenvía. La construcción falla en cualquier cosa que parezca una clave, token, clave privada, JWT, asignación de contraseña o credenciales en una URL (también se usa gitleaks cuando está instalado). Elimínalo del contenido; nunca lo "enmascares" manualmente. Los secretos en prompts registrados se enmascaran automáticamente.

Escribe estructura, no prosa

Cada campo de texto renderiza estructura, así que dale estructura:

• - elemento → viñetas; 1. elemento → numeradas (solo secuencias reales); dos o más líneas Clave: valor → una tabla alineada; un array JSON de cadenas → viñetas.
• **negrita** para la(s) una o dos cosas por línea que el lector no debe perderse; ==texto== para resaltar; `código` para identificadores, rutas, comandos.
• Sin párrafo de más de dos oraciones; sin subtítulos ni líneas introductorias.

Orientación de campos: brief — 1–3 líneas Clave: valor para la tarjeta del mapa. problem — hechos clave/valor. goal — viñetas de lo que significa "hecho". result.summary — clave/valor o viñetas.

Idioma

Contenido en el idioma del usuario, meta.lang configurado con su código. Las etiquetas de estructura permanecen en inglés.

Archivos

• assets/template.html — la estructura: marcado con marcadores de posición, estilos, iconos y un script para diseño, navegación, búsqueda, el carril de prompts y las respuestas.
• scripts/build.py — valida el contenido (verificaciones anteriores, secretos), sella el diario, renderiza la plantilla. --check solo valida; --template usa otra plantilla.
• scripts/track.py — start, wait, hook, stop-hook, daemon, status, install-hook (consulta su docstring).
• scripts/statusline.py — el enlace del informe para la barra de estado de Claude Code.
• references/schema.md — todos los campos.
• examples/ — ejemplos en inglés y ruso; el ejemplo ruso incluye un diario de 5 prompts.