Cómo escribir un buen informe de error (para una IA o un desarrollador)

Un buen informe de error permite que otra persona, un desarrollador o una IA, vea el mismo problema que tú sin tener que hacerte ninguna pregunta. Necesita un título concreto, los pasos exactos para reproducirlo, lo que esperabas, lo que ocurrió realmente, cualquier mensaje de error copiado palabra por palabra y dónde ocurrió: en qué página, navegador, dispositivo y con qué usuario. Un error por informe, con una captura de pantalla si ayuda.

La mayoría de los errores tardan más en entenderse que en arreglarse. Un informe claro elimina la parte de entender. Esto importa aún más con las herramientas de IA: una IA no puede hacerte una pregunta de seguimiento sobre lo que querías decir con “el pago es raro”, así que adivina, y una suposición equivocada puede romper otra cosa.

La plantilla

Copia esto y rellénalo:

Título: [Qué falla y dónde] — p. ej. "El formulario de reservas rechaza horas después de las 18:00"

Pasos para reproducirlo:
1. ...
2. ...
3. ...

Esperado: [qué debería pasar]
Real: [qué pasó en su lugar]

Mensaje de error: [texto exacto, si lo hay]
Dónde: [página/URL, navegador, dispositivo, con qué usuario has iniciado sesión]
Frecuencia: [siempre / a veces / una vez]
Captura o grabación: [adjunta]

El resto de esta guía explica cada parte.

Paso 1: Reprodúcelo primero

Antes de escribir, intenta que el error vuelva a ocurrir. Así sabrás qué pasos importan y si ocurre siempre.

• Empieza desde un estado limpio: recarga, o cierra la sesión y vuelve a entrar.
• Anota cada clic y cada cosa que escribas.
• Busca el camino más corto que lo provoca.
• Prueba con otro navegador o cuenta. Si solo ocurre con un usuario, es una gran pista.

Para profundizar, consulta cómo depurar una app creada con IA.

Paso 2: Escribe un título concreto

El título debe decir qué falla y dónde, para que alguien que mira una lista sepa de qué error se trata.

Paso 3: Enumera los pasos exactos

Numéralos. Sé literal: qué página, qué botón, qué escribiste.

1. Inicia sesión como cliente (cuenta de prueba: customer@example.com).
2. Añade el “Kit de inicio” al carrito.
3. Introduce el código de descuento WELCOME10 y haz clic en Aplicar.
4. Haz clic en Pagar.

“Prueba a pagar con un código” omite los detalles que suelen importar: qué usuario, qué producto, qué código y si se aplicó antes.

Paso 4: Esperado frente a real

Este es el núcleo del informe. Di ambas cosas, porque la diferencia es el error.

• Esperado: la página de pago se abre con el 10 % de descuento reflejado en el total.
• Real: el botón muestra un cargando durante un segundo y después no pasa nada. Sin código de descuento, el pago funciona.

Sin “esperado”, quien lee puede no saber que el comportamiento es incorrecto. Sin “real”, no sabe qué buscar.

Paso 5: Copia los errores exactamente

Los mensajes de error son la vía más rápida hacia la causa. Cópialos como texto, palabra por palabra; no los parafrasees.

Dónde encontrarlos:

• En pantalla: cualquier mensaje que muestre la app.
• Consola del navegador: abre las herramientas de desarrollador (F12, o clic derecho → Inspeccionar) y mira la pestaña Console en busca de líneas en rojo.
• Pestaña Network: en las herramientas de desarrollador, busca la petición fallida y anota su URL y su código de estado (por ejemplo POST /api/checkout → 500).
• Registros del servidor, si tienes acceso.

Una línea como TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 a menudo apunta directamente al problema.

Paso 6: Añade contexto

• Dónde: la URL de la página, el entorno (vista previa, pruebas o producción).
• Quién: qué usuario o rol: administrador, miembro, sin sesión iniciada.
• Dispositivo y navegador: “Safari en iPhone” frente a “Chrome en Windows” puede importar.
• Datos: cualquier cosa poco habitual del registro: texto muy largo, caracteres especiales, un número grande de elementos.
• Cuándo empezó: “después del cambio de ayer en los códigos de descuento” es oro puro.
• Con qué frecuencia: siempre, o una de cada diez veces.

Paso 7: Muéstralo

Una captura con el problema marcado, o una grabación corta de pantalla, elimina la ambigüedad, sobre todo en los errores de diseño. Si tu herramienta de IA admite imágenes, adjunta una. Recorta cualquier dato privado, incluidas claves y datos de otras personas.

Escribir informes de error para un creador con IA

La misma estructura funciona como prompt. Dos añadidos ayudan:

• Di qué no debe cambiar, para que la solución no cause un problema nuevo.
• Pide que verifique la solución, no solo que la escriba.

Con sesión iniciada como cliente, con el “Kit de inicio” en el carrito y el código WELCOME10 aplicado, al hacer clic en Pagar no pasa nada. Esperado: se abre la página de pago con un 10 % de descuento en el total. Real: un breve cargando y después nada. La pestaña Network muestra que POST /api/checkout devolvió 500. Pagar sin código funciona. Encuentra la causa y arréglala sin cambiar cómo se calculan los precios de los pedidos sin código. Luego prueba el pago con un código porcentual, un código de importe fijo y sin código.

Si no estás seguro de la causa, pide primero un diagnóstico:

No cambies el código todavía. Según este informe, ¿cuáles son las causas probables y qué confirmaría cada una?

Errores comunes

• “Está roto”. Sin pasos, sin resultado esperado, nada sobre lo que actuar.
• Varios errores en un informe. Algunos se arreglan y otros se pierden.
• Errores parafraseados. “Algo undefined” oculta la parte útil.
• No indicar el usuario o el rol. Muchos errores solo afectan a administradores o solo a usuarios nuevos.
• Describir solo la solución que quieres (“añade una comprobación de nulos”) en lugar del problema.
• Compartir secretos en capturas o registros pegados.

Lista de verificación

• Reproduje el error y encontré los pasos más cortos.
• El título dice qué falla y dónde.
• Los pasos están numerados y son literales.
• Indico tanto lo esperado como lo real.
• Los mensajes de error están copiados exactamente, con la petición fallida y el código de estado.
• Incluyo página, entorno, usuario, dispositivo y navegador.
• Indico con qué frecuencia ocurre y cuándo empezó.
• Adjunto una captura o grabación, sin datos privados.
• Un error por informe.

Informar de errores al agente de Mythex

En un proyecto de Mythex, el informe es el prompt. Algunas funciones ayudan:

• Adjunta una captura de la vista previa o de la pantalla de error: hasta 5 archivos por mensaje.
• /fix centra al agente en arreglar un error; el modo Plan le permite investigar antes de editar.
• /test hace que el agente reproduzca los flujos en la propia vista previa e informe de lo que ve.
• Volver a este punto deshace una corrección que empeoró las cosas.

La página de depuración con prompts de la documentación usa la misma estructura de pasos, esperado y real. Para el ciclo de corregir y comprobar que rodea a esto, consulta cómo iterar en una app creada con IA.

Preguntas