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ú viste, sin tener que preguntarte nada. Necesita un título específico, los pasos exactos para reproducirlo, lo que esperabas, lo que ocurrió en realidad, cualquier mensaje de error copiado palabra por palabra y dónde ocurrió: en qué página, navegador, dispositivo y 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 esa parte de comprensión. Esto importa todavía 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

Cópiala y rellénala:

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

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

Esperado: [lo que debería pasar]
Real: [lo que 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]
Con qué 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 aparecer. Así sabrás qué pasos importan y si ocurre siempre.

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

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

Paso 2: Escribe un título específico

El título debe decir qué falla y dónde, para que alguien que recorra 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.

«Intenta pagar con un código» omite los detalles que a menudo importan: qué usuario, qué producto, qué código y si se aplicó antes.

Paso 4: Esperado frente a real

Esta es la parte esencial del informe. Indica ambas cosas, porque la diferencia es el error.

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

Sin «esperado», quien lo lea podría 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 hasta 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 desarrollo (F12, o clic derecho → Inspeccionar) y mira la pestaña Consola en busca de líneas rojas.
• Pestaña de red: en las herramientas de desarrollo, localiza la petición que falla 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 y 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 inusual 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 vez de cada diez.

Paso 7: Muéstralo

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

Escribir informes de error para un creador con IA

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

• Indica 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 la 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: la página de pago se abre con un 10 % de descuento en el total. Real: un breve indicador de carga y luego nada. La pestaña de red 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. Después, comprueba el pago con un código porcentual, con 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, sin nada en que actuar.
• Varios errores en un solo informe. Algunos se arreglan y otros se pierden.
• Errores parafraseados. «Una cosa indefinida» 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 en registros pegados.

Lista de comprobación

• He reproducido el error y encontrado los pasos más cortos.
• El título dice qué falla y dónde.
• Los pasos están numerados y son literales.
• Se indican tanto lo esperado como lo real.
• Los mensajes de error están copiados exactamente, con la petición que falla y su código de estado.
• Se incluyen la página, el entorno, el usuario, el dispositivo y el navegador.
• He indicado con qué frecuencia ocurre y desde cuándo.
• Hay una captura o grabación adjunta, 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.
• Revertir a este punto deshace una solució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 arreglar y comprobar que la rodea, consulta cómo iterar en una app creada con IA.

Preguntas