Plantilla de informe de errores que los fundadores pueden usar para conseguir arreglos más rápidos

Por qué los ingenieros se atascan con informes de errores vagos

Un informe de errores vago no falla porque sea corto. Falla porque deja demasiadas causas posibles. Los ingenieros acaban adivinando, probando arreglos al azar o perdiendo tiempo recreando tu situación exacta.

“Hice clic y se rompió” suele ocultar los detalles importantes: en qué página estabas, qué clicaste, qué escribiste y qué esperabas que pasara. Para un ingeniero, eso puede ser un bug de front-end, un error de back-end, un fallo de permisos, una caché del navegador corrupta o un fallo de red puntual. Sin una ruta clara para reproducirlo, el bug puede parecer invisible.

Incluso cuando el bug es real, puede ocurrir solo bajo ciertas condiciones. Tal vez solo pasa con cuentas nuevas, solo después de un restablecimiento de contraseña, solo en un plan específico o solo cuando un campo queda vacío. Si esas condiciones no se anotan, el equipo puede probar la ruta feliz y concluir que “funca en mi máquina”.

No necesitas ser técnico para ayudar. Tu trabajo es ser específico y consistente, para que otra persona pueda seguir tus pasos y ver la misma falla.

Si tienes 5 minutos, haz estas cosas de alto impacto:

• Escribe los pasos exactos que tomaste, una acción por línea
• Copia el texto exacto del error (o captura una pantalla)
• Di qué esperabas que pasara vs lo que pasó
• Anota el dispositivo y el navegador que usaste
• Inténtalo de nuevo en una ventana privada para ver si se repite

Un informe claro vence siempre a un mensaje largo. Una página con pasos precisos es más útil que diez párrafos de contexto.

Si trabajas con un prototipo generado por IA que se comporta de forma impredecible, la claridad importa aún más. Pequeños detalles pueden desencadenar fallos grandes.

Qué incluye un informe de bug accionable

Un informe de bug accionable permite que un ingeniero reproduzca el problema, entienda el impacto y sepa cuándo el arreglo está terminado. Si falta cualquiera de esas piezas, el informe se convierte en un juego de adivinanzas.

Empieza por facilitar la localización del bug. Nombra el lugar exacto donde ocurre (página, función, pantalla o ruta API) y la acción que lo desencadena. “Falla el checkout” es vago. “Checkout: al hacer clic en Pagar en el paso Envío responde con 500” es algo que un desarrollador puede buscar.

A continuación, define los límites. Señala qué está afectado y qué no. Esto evita probar áreas no relacionadas.

Ejemplos:

• Solo ocurre para usuarios nuevos; los que regresan pueden pagar
• Solo falla en móvil; en escritorio está bien

Incluye lo esencial en lenguaje llano:

• Dónde ocurre (pantalla, ruta URL o nombre de la función)
• Cómo reproducirlo (una secuencia corta que otra persona pueda seguir)
• Qué esperabas que pasara vs qué pasó realmente
• Qué tan urgente es (venta bloqueada, fallo de UI menor, caso extremo raro)
• Qué significa “hecho” (el resultado exacto que quieres después del arreglo)

Un buen informe también muestra impacto sin dramatismo. “Los usuarios no pueden iniciar sesión, por lo que no llegan al panel” es más útil que “¡Esto es crítico!!!”. Si tienes números, añádelos: “3 de 5 cuentas de prueba lo sufrieron”.

Mantenlo comprobable. Si el informe pide un arreglo pero no describe una comprobación, el ingeniero no puede enviar con confianza. Una simple declaración de “hecho” ayuda, por ejemplo: “Un usuario nuevo puede registrarse, confirmar el email y llegar a la pantalla principal sin error.”

Si usas una base de código generada por IA (de herramientas como Cursor o Replit), incluye ese contexto también. A menudo cambia dónde miran primero los ingenieros y puede afectar el alcance y el riesgo.

La plantilla de informe de bug amigable para fundadores (copia y completa)

Usa esta plantilla cuando quieras que un ingeniero reproduzca el problema rápido y envíe un arreglo sin mucho ida y vuelta.

TITLE
[What broke] in [where: page/feature] for [who: user type]
Example: “Checkout error on Payment step for logged-in users”

IMPACT
- Who is blocked:
- How often it happens (every time / sometimes / first time today):
- Business effect (can’t sign up, can’t pay, data wrong, security risk):

STEPS TO REPRODUCE (numbered, exact)
1) Start state (logged out/in, which account, which plan):
2) Go to:
3) Click/type:
4) Select:
5) Submit/refresh/wait:

EXPECTED VS ACTUAL (one sentence each)
Expected:
Actual:

ENVIRONMENT (what you used when it failed)
- Device (phone/laptop, model if known):
- OS version:
- Browser + version (or app version):
- Account type/role (admin, member, trial, paid):
- Time it happened + timezone:

SMALLEST REPRODUCIBLE CASE
What is the minimum setup that still fails?
- Smallest test account/data needed:
- One setting/flag that seems required:
- Minimal path (fewest steps) that still triggers it:

NOTES (optional)
- First time you noticed it:
- Recent changes (new prompt-generated code, new deploy, new integration):
- Workaround (if any):

Consejo: si puedes reproducirlo en una cuenta de prueba nueva con un registro de muestra, inclúyelo. A menudo reduce el tiempo de depuración a la mitad.

Paso a paso: cómo escribir los pasos de reproducción

Los pasos de reproducción son la forma más rápida de convertir una queja en un arreglo. El objetivo es simple: hacer posible que alguien que nunca ha visto tu app alcance el mismo bug en menos de 2 minutos.

Empieza desde un estado limpio para que tus pasos coincidan con lo que experimenta la mayoría de usuarios. Eso suele significar cerrar sesión, hacer un hard refresh o abrir una nueva pestaña (privada/incógnita ayuda). Si el bug depende de estar logueado, dilo e incluye qué tipo de usuario usaste.

Escribe los pasos como una receta, no como una historia. Usa los nombres exactos que la gente ve en pantalla: títulos de página, etiquetas de botones, nombres de campos y elementos de menú. Si tu UI dice “Crear espacio de trabajo” pero tú escribes “añadir un espacio”, un ingeniero puede acabar en el lugar equivocado.

Una lista rápida que puedes reutilizar:

• Restablece a un estado limpio (cerrar sesión, refrescar, nueva pestaña)
• Asume que el lector es nuevo en el producto
• Usa el texto UI exacto (botones, páginas, campos)
• Incluye los datos que ingresaste (email, plan, ejemplo de entrada)
• Detente en el primer momento en que aparece el bug

Un ejemplo concreto (buen nivel de detalle): abres una nueva ventana incógnita, vas a la página de Login, inicias sesión con [email protected] (rol Admin), clicas “Billing” en el menú izquierdo, clicas “Upgrade plan”, seleccionas “Pro” y clicas “Confirm”. El bug aparece justo después de clicar “Confirm” (la página se congela y el spinner no para).

Un cambio que ayuda inmediatamente: no mezcles síntomas y conjeturas en los pasos. Mantén los pasos puros y guarda tus pensamientos para una línea separada de “Notas”.

Comportamiento esperado vs real (hazlo inequívoco)

La forma más rápida de obtener un arreglo es describir el resultado que querías (esperado) y el resultado que obtuviste (real) en palabras sencillas y comprobables. Piensa en “esperado” como la meta del usuario, no en cómo está construida la app.

Comportamiento esperado debe leerse como una promesa simple al usuario. Bueno: “Después de clicar Pagar, el pedido se crea y veo una página de confirmación con un número de pedido.” No tan bueno: “El webhook de Stripe debería dispararse y actualizar la BD.” (Eso es una conjetura de implementación.)

Comportamiento real es lo que puedes ver y copiar. Incluye el texto exacto del error, etiquetas de botones y lo que muestra la página. Si hay un mensaje de error, pégalo exactamente. Si no aparece ningún mensaje, dilo también.

Las fallas parciales importan. Muchos bugs son casos de “funciona, pero…”: inicia sesión pero muestra la cuenta equivocada, guarda pero cambia la fecha, sube pero pierde el nombre del archivo. Señala qué funcionó y qué está mal para que los ingenieros no se queden en el primer “éxito”.

Para hacer esta sección fácil de escanear, usa este mini formato:

• Esperado: (una oración con el resultado del usuario)
• Real: (lo que viste, incluye texto exacto)
• Frecuencia: siempre / a veces / solo la primera vez (añade % si puedes)
• Lo que intenté: (restablecer contraseña, otro navegador, recargar, etc.)

Ejemplo: Esperado: “La invitación envía un email en 1 minuto.” Real: “El toast dice ‘Invite sent’, pero no llega el email. No se muestra error. El usuario aparece en la lista con estado Pending.” Frecuencia: “Pasa 3 de 5 veces.” Lo que intenté: “Probé dos emails, esperé 10 minutos, miré spam, reintenté una vez.”

Detalles del entorno que los ingenieros realmente necesitan

Si un bug solo ocurre para algunas personas, la forma más rápida de desbloquear un arreglo es escribir la configuración exacta donde falla. Sin eso, los ingenieros pueden pasar horas probando en el dispositivo equivocado, el tipo de cuenta equivocado o la red equivocada.

Incluye estos básicos cuando puedas:

• Navegador + versión (ejemplo: Chrome 121, Safari 17). Si es en una app, incluye la versión de la app.
• Dispositivo + SO (ejemplo: iPhone 14 en iOS 17.2, portátil con Windows 11, macOS 14).
• Estado de la cuenta (usuario nuevo vs existente, admin vs miembro, plan de pago vs gratuito, invitado vs registro propio).
• Ventana de tiempo + zona horaria (ejemplo: “18 ene, 9:30-10:00am PT”). Esto ayuda a emparejar logs del servidor.
• Notas de red (Wi‑Fi doméstica vs oficina, celular, VPN activada/desactivada, país). Algunos bugs solo aparecen tras ciertos VPN o en regiones concretas.

Una forma simple de capturar esto es copiar la pantalla “About” o la versión de tu navegador/app y añadir una línea sobre quién tenías logueado.

Ejemplo:

“Falla en Safari 17.1 en iPhone (iOS 17.2). Funciona en Chrome 121 en mi Mac. Estoy logueado como admin pagado existente. Pasó hoy alrededor de 10:15am ET. VPN activo (ubicación EEUU).”

Si heredaste una app generada por IA y el comportamiento cambia entre navegadores o cuentas, eso es una pista fuerte de que el código tiene casos límite ocultos. En esa situación, muchos equipos empiezan recreando tu entorno exacto, luego parchean la lógica y endurecen los puntos débiles para que el bug deje de reaparecer.

Encontrar el caso reproducible mínimo

Un “caso reproducible mínimo” es la ruta más corta que sigue fallando de la misma manera, cada vez. Los ingenieros arreglan más rápido cuando pueden desencadenar el problema a demanda, sin adivinar qué detalle importó.

Empieza por quitar cualquier cosa que no sea necesaria para que el bug ocurra. Si puedes borrar un paso y el bug sigue sucediendo, ese paso era ruido. Si una página tiene tres acciones, trata de reducirlo al clic, envío de formulario o llamada API que desencadena el problema.

Una forma práctica de reducir el problema es cambiar a una configuración limpia. Los datos reales de clientes suelen añadir confusión (permisos, registros antiguos, casos límite). Usa una cuenta de prueba nueva y una entrada de ejemplo simple y repetible.

Un método que funciona aunque no seas técnico:

• Reproduce el bug una vez y anota cada paso que hiciste
• Repítelo, pero omite un paso (o usa datos más simples) para ver si aún falla
• Pasa a una cuenta de prueba limpia y prueba con la entrada más simple posible
• Redúcelo a una sola página y una acción, si es posible
• Mantén la única entrada de muestra que lo dispara al 100%

Luego escribe dos versiones de los pasos: la ruta mínima y la historia completa. La ruta mínima es lo que un ingeniero ejecutará primero; la historia completa es contexto que puede explicar por qué importa.

Ejemplo: el signup de tu app generada por IA falla solo para algunos usuarios. La historia completa puede implicar invitaciones, un plan de pago y un dominio de email específico. El caso mínimo reproducible podría ser: “Cuenta de prueba nueva -> Signup -> Introducir email [email protected] -> Submit -> Error.”

Evidencia: errores, capturas y grabaciones sin ruido

Buena evidencia convierte un “puedes arreglar esto?” en algo que los ingenieros pueden actuar rápido. El objetivo es sencillo: hacer la falla obvia y facilitar emparejar lo que viste con lo que hay en los logs.

Primero, copia el texto exacto del error. No parafrasees. Pégalo con la misma puntuación, redacción y cualquier código. Si la UI muestra un ID (ID de pedido, ID de usuario, número de factura, nombre del workspace), inclúyelo también. Esas cadenas suelen permitir a un ingeniero encontrar la entrada correcta en los logs en segundos.

Las capturas ayudan más cuando muestran contexto. Una captura recortada de un toast puede ser engañosa porque oculta en qué página estabas y qué campos estaban rellenados. Captura la pantalla completa, incluyendo la barra de URL si es una app web, y los inputs visibles.

Las grabaciones son aún mejores cuando el problema depende del tiempo o de una ruta de clics específica. Manténlas cortas (20–60 segundos), pero incluye los pasos previos y el momento exacto en que falla.

Evidencia más útil, en orden:

• Mensaje de error exacto (copiar/pegar), más cualquier ID visible
• Captura de pantalla de pantalla completa justo después del fallo
• Grabación corta mostrando los pasos y la falla
• Qué ingresaste o seleccionaste (valores de formulario), con secretos eliminados
• Marca temporal y tu zona horaria (ayuda a emparejar logs)

Ejemplo: “Checkout falla con ‘Payment session invalid.’ Order ID: 18492. La captura muestra la página de checkout con el cupón aplicado. La grabación muestra: Carrito -> Aplicar cupón SAVE10 -> Pagar -> error. Usé tarjeta de prueba terminada en 4242. No hay datos reales de clientes.”

Si compartes valores de formulario, elimina contraseñas, claves API y números completos de tarjeta. Sustituye por marcadores como [REDACTED].

Ejemplo: un informe realista de un fundador

Aquí tienes un ejemplo completado. Escenario: un usuario nuevo intenta registrarse pero queda atrapado en un bucle de restablecimiento de contraseña.

Title
- Signup sends users into password reset loop

Impact
- New users cannot create accounts. This blocks onboarding and sales demos.

Urgency
- High (we have 3 demos tomorrow). If there’s a safe workaround, that’s fine for now.

Where it happens
- /signup page and the “Forgot password” email link

Reproduction steps
1) Open the app in Chrome.
2) Go to /signup.
3) Enter a new email that has never signed up before.
4) Enter a password (any).
5) Click “Create account”.
6) You see “Account already exists. Reset your password”.
7) Click “Reset password”.
8) Open the reset email and click the link.
9) After setting a new password, you return to /signup and step 6 happens again.

Expected behavior
- Step 5 creates a new account and logs the user in.

Actual behavior
- The app claims the account exists and forces password reset, but the reset does not allow signup to complete.

Environment
- Browser: Chrome 121 (also reproduced on Safari iOS 17)
- Device: MacBook + iPhone
- Account state: email never used before
- Time: started today around 10:30am local

Evidence
- Error shown: “Account already exists. Reset your password”
- Console error: POST /api/auth/signup 409
- Server log snippet: Unique constraint failed on users.email

Workaround tried
- Tried a different email. Same behavior.
- Cleared cookies. No change.

Notes
- Project was generated with an AI tool and then edited in Cursor.

Detalles que los fundadores suelen pasar por alto al principio: si el email se usó antes (incluso en staging), si el problema ocurre en otro navegador y el código de error exacto (409 importa).

Cómo el caso reproducible mínimo lo afina: “Nuevo email + clic Crear cuenta = 409 en /api/auth/signup cada vez.” Eso apunta directamente a creación duplicada de usuario o a un flujo de auth que mezcla signup y reset.

El impacto y la urgencia quedan claros sin ruido: bloquea onboarding y hay una fecha límite.

Errores comunes (y cómo evitarlos)

La mayoría de arreglos lentos no son “bugs difíciles”. Son detalles que faltan. Una plantilla sirve principalmente para eliminar la adivinanza y que un ingeniero reproduzca el problema rápido.

1) Los pasos empiezan desde un lugar vago

Si tus pasos comienzan con “abre la app” o “inicia sesión”, el ingeniero no sabe en qué estado estabas. Empieza con un punto de partida claro: qué página, qué cuenta usaste (admin vs normal) y si los datos ya existían.

Arreglo simple: añade una línea antes de los pasos como “Estado inicial: logueado como usuario plan gratis, en la página de Settings, sin equipo creado.”

2) Parafraseas el error (o lo omites)

“Error del servidor” y “se cayó” no son suficientes. Copia el texto exacto del error. Si hay un código (500, 401, “JWT expired”, “SQLSTATE”), inclúyelo. Las palabras exactas suelen apuntar a un archivo o servicio específico.

3) Combinas múltiples problemas en un solo informe

Los ingenieros pueden arreglar una cosa rápido o tres cosas lento. Si el login falla y el dashboard carga lento, crea dos informes separados. Si no estás seguro de si están relacionados, dilo, pero mantenlos separados.

Errores comunes y la solución rápida:

• Demasiados pasos: corta lo que no cambia el resultado
• Falta el gatillo: escribe el clic, input o llamada API exacta que lo causa
• No hay resultado esperado: di qué pensabas que pasaría
• Sin entorno: incluye dispositivo, navegador y versión/build
• Incluiste datos sensibles: reemplázalos por valores falsos y anota lo que cambiaste

4) Compartes secretos o datos privados

Los fundadores a menudo pegan logs que contienen claves de API, cookies o emails reales. Antes de enviar, redáctalos. Si trabajas con una app generada por IA (por ejemplo con Bolt, v0, Cursor o Replit), los secretos expuestos son comunes, así que ten más cuidado.

5) Reportas el síntoma, no el gatillo

“No guarda” es un síntoma. El gatillo es “escribo X en el campo Y, clico Guardar y al refrescar el cambio desaparece.” Si lo reduces al caso reproducible mínimo, el arreglo suele venir rápido.

Lista rápida y próximos pasos

Si solo haces una cosa, usa una plantilla consistente para que cada informe llegue con los detalles que un ingeniero necesita para reproducir y arreglarlo.

Lista rápida para copiar y pegar

• Título + impacto: Qué está roto y qué bloquea (checkout falla, signup atascado, datos incorrectos)
• Pasos para reproducir: Numerados, clicks e inputs exactos, empezando desde un punto claro
• Comportamiento esperado: Qué debería pasar (una oración)
• Comportamiento real: Qué pasa en su lugar (incluye mensaje exacto si hay)
• Evidencia: Una captura/registro limpio o el texto clave del error (sin ruido)

Antes de enviarlo, añade los detalles del entorno que suelen explicar los problemas de “funciona en mi máquina”: tipo de dispositivo, versión del SO, navegador y versión (o versión de la app), cuenta/rol usada y la hora en que ocurrió (con zona horaria si tu equipo es remoto).

Comprobaciones finales (toma 60 segundos)

• Prueba de reproducción: ¿Alguien más puede seguirlo en menos de 2 minutos sin adivinar?
• Caso mínimo: Quita pasos opcionales hasta que falle en el flujo más simple
• Seguridad: Elimina contraseñas, claves API, tokens y datos personales de capturas/logs
• Ejecución fresca: Prueba en ventana privada o tras logout/login y anota el resultado
• Si es código generado por IA: Cuando los fallos se acumulan (auth roto, secretos expuestos, estructura desordenada), empieza con un diagnóstico focalizado

Si tu app fue construida con herramientas de IA y sigue fallando en producción, FixMyMess puede ayudar diagnosticando la base de código, reparando la lógica rota y endureciendo problemas de seguridad que suelen estar detrás de bugs “aleatorios”. Si quieres un mapa claro de lo que falla antes de comprometerte a cambios, su auditoría de código gratuita está pensada para eso.