Depura informes de errores que no escribiste con un flujo práctico para reproducir problemas, aislar UI/API/BD y solicitar una corrección mínima y comprobable por IA.
Depurar un informe de error que no escribiste es más difícil porque te falta el mapa mental del autor original. No sabes qué es frágil, qué es “normal” ni qué atajos se tomaron. Un síntoma pequeño (un botón, un error tipográfico, una pantalla lenta) puede provenir de un problema más profundo en la API, la base de datos o un job en segundo plano.
Un informe útil te da cuatro cosas:
La mayoría de los informes solo dan lo último: “Guardar no funciona”, “está roto”, “error aleatorio”. Lo que falta es el contexto que lo hace repetible: rol de usuario, registro específico, entorno (prod vs staging) y si empezó tras un cambio.
El objetivo es convertir un síntoma vago en una reproducción fiable. Una vez que puedes provocarlo a demanda, deja de ser misterioso. Es una serie de comprobaciones.
Lo que puedes controlar de inmediato:
“Listo” no es “creo que lo arreglé”. Listo es: tus pasos de reproducción pasan tras un pequeño cambio y vuelves a probar rápidamente el comportamiento cercano que pudiste haber afectado.
La forma más rápida de perder tiempo es cambiar varias cosas a la vez. Congela tu punto de partida para que cada resultado de prueba signifique algo.
Elige un entorno y quédate en él hasta poder reproducir el problema. Si el informe vino de producción, confírmalo allí primero. Si eso es arriesgado, usa staging. Local está bien si puedes igualar de cerca los datos y la configuración.
Luego deja claro qué código se está ejecutando: versión, fecha de build y cualquier feature flag o config que afecte el flujo. Pequeñas diferencias (integraciones deshabilitadas, URL base de API distinta, jobs en segundo plano faltantes) pueden convertir un bug real en un fantasma.
Crea una configuración de prueba limpia y repetible. Usa una cuenta nueva y datos conocidos. Si puedes, restablece el estado antes de cada intento (cerrar sesión, limpiar caché, empezar desde el mismo registro).
Escribe las suposiciones mientras avanzas. No es papeleo: evita discutir contigo mismo más tarde.
Plantilla de nota de línea base:
Si no reproducir, estas notas te dicen qué variar a continuación, una perilla a la vez.
La victoria más rápida es convertir una queja vaga en algo que puedas ejecutar como un script.
Empieza reescribiendo el informe como una breve historia de usuario: quién hace qué, dónde y qué esperaba. Luego añade el resultado observado.
Ejemplo reescrito:
"Como administrador de facturación, cuando cambio el estado de una factura a Paid y hago clic en Guardar en la página de la factura, el estado debería persistir. En su lugar, la página permanece igual y el estado no cambia después de actualizar."
A continuación, captura las condiciones que hacen verdadero el informe. Los bugs suelen depender de un detalle faltante: rol, estado del registro, locale o entorno.
Entradas clave para anotar antes de clicar:
Recopila evidencia mientras aún tienes el comportamiento original. Las capturas ayudan, pero una grabación corta es mejor porque captura los tiempos y clics exactos. Siempre anota un timestamp (con zona horaria) para poder emparejar los logs después.
Tres preguntas aclaratorias que quitan la mayor parte de las conjeturas:
No empieces adivinando la causa. Haz que el problema ocurra a propósito, de la misma forma, más de una vez.
Primero, ejecuta exactamente los pasos del reportero. No los “mejores”. Anota el primer punto donde tu experiencia diverge, aunque parezca menor (etiqueta de botón diferente, campo que falta, texto de error ligeramente distinto). Esa primera discrepancia es a menudo la pista.
Un flujo sencillo que funciona en la mayoría de apps:
Después de que sea repetible, varía una cosa a la vez. Pruebas de una sola variable que suelen dar resultado:
Termina con un script corto de repro que alguien más pueda ejecutar en 2 minutos: estado inicial, pasos, inputs y la primera observación fallida.
Antes de leer todo el código, decide qué capa está fallando.
Pregúntate: ¿el síntoma está solo en la UI o también en los datos y en las respuestas de la API?
Ejemplo: “Mi nombre de perfil no se actualizó.” Si la API devuelve el nombre nuevo pero la UI sigue mostrando el antiguo, sospecha del estado de UI/caché. Si la API nunca lo guardó, probablemente estés en API o BD.
Preguntas rápidas de triage que puedes responder en minutos:
Las comprobaciones de UI van de la visibilidad: errores en la consola, la pestaña Network y estado obsoleto (UI que no vuelve a solicitar después de guardar o que lee de una caché antigua).
Las comprobaciones de API van del contrato: payload (campos, tipos, IDs), código de estado y cuerpo de error. Un 200 con un body sorprendente puede importar tanto como un 400.
Las comprobaciones de BD van de la realidad: filas faltantes, escrituras parciales, fallos de constraints, updates que afectan cero filas porque el WHERE no coincidió.
Para mantenerte orientado, dibuja un pequeño mapa: qué acción UI dispara qué endpoint y qué tabla(s) lee o escribe.
La claridad a menudo viene de seguir una petición real desde el clic hasta la base de datos y de regreso.
Captura tres anclas del informe o de tu repro:
Si no tienes correlation ID, añade uno en tu gateway/backend e inclúyelo en cabeceras de respuesta y logs.
Para no ahogarte en ruido, captura solo lo necesario para responder “¿Dónde falló y por qué?”:
Señales a vigilar:
Si “iba ayer y hoy no”, sospecha deriva del entorno: flags cambiados, secretos rotados, migraciones faltantes o jobs que dejaron de correr.
El bug más fácil de arreglar es un experimento pequeño y repetible.
Reduce todo: menos clics, menos campos, el dataset más pequeño que aún falla. Si solo ocurre con “clientes con muchos registros”, intenta crear el caso mínimo que aún lo dispare. Si no puedes, eso indica que el bug puede depender del volumen de datos.
Separa “estado malo” de “código malo” restableciendo el estado a propósito: cuenta limpia, tenant o dataset nuevo, build conocido.
Una forma práctica de mantener el repro claro es una tabla compacta de inputs:
| Dado (setup) | Cuando (acción) | Espero | Obtuve |
|---|---|---|---|
| Rol: Editor; un registro con Status=Draft | Clic en Guardar | Toast “Saved” + timestamp actualizado | Botón muestra spinner y luego para; sin cambio |
Haz el repro portable para que alguien más lo ejecute rápido:
El camino más rápido suele ser aburrido: cambia una cosa, observa y toma notas.
Errores comunes:
Un ejemplo realista: un ticket dice “Export CSV está vacío.” Tú pruebas con una cuenta admin y ves datos. El usuario tiene un rol restringido y la API devuelve una lista vacía por un filtro de permisos. Si solo parcheas la UI para mostrar “Sin filas”, te pierdes la pregunta real: ¿ese rol debería poder exportar o el producto debe explicar por qué está filtrado?
Tras cualquier arreglo, vuelve a ejecutar los pasos exactos del repro y luego prueba un escenario cercano que debería seguir funcionando.
Obtendrás mejores respuestas de un compañero (o de una herramienta) si llevas un paquete cerrado: pasos repetibles, una capa probablemente fallida y prueba.
Antes de que alguien cambie código, confirma:
Luego haz una pasada rápida de regresión: prueba otro rol, una segunda ventana/navegador privado, una funcionalidad cercana que use el mismo endpoint/tabla y un input de borde (vacío, texto muy largo, caracteres especiales).
Un mensaje de soporte dice: “El botón Guardar no hace nada en el formulario Edit Customer.” Un seguimiento revela que solo ocurre para clientes creados antes del mes pasado y únicamente cuando cambias el email de facturación.
Empieza en la UI y asume la falla más simple primero. Abre el registro, haz la edición y busca señales de que “nada” es en realidad algo: botón deshabilitado, toast oculto, mensaje de validación que no se renderiza. Luego abre la consola del navegador y la pestaña Network.
Aquí, al hacer clic en Guardar se dispara una petición, pero la UI nunca muestra el resultado porque el frontend solo trata el 200 como éxito e ignora errores 400. La pestaña Network muestra una respuesta 400 con un body JSON como: {"error":"billingEmail must be unique"}.
Ahora verifica que la API realmente falla: toma el payload exacto de la petición y reprodúcelo fuera de la UI. Si falla también fuera de la UI, deja de perseguir estados frontend.
Luego revisa la base de datos: ¿por qué la unicidad falla solo en registros antiguos? Descubres que clientes legacy comparten un billing_email placeholder de hace años. Una validación de unicidad nueva ahora bloquea guardar cualquier cliente que aún use ese placeholder.
Repro mínimo que puedes entregar:
billing_email = [email protected].billingEmail must be unique.Criterio de aceptación: cuando la API devuelva un error de validación, la UI muestra el mensaje, conserva las ediciones del usuario y el error nombra el campo exacto que falló.
Una vez reproducible y con la capa probable identificada, pide ayuda de forma que produzca un parche pequeño y seguro.
Empaqueta un “expediente” simple: pasos mínimos de repro (con inputs, entorno, rol), esperado vs real, por qué crees que es UI/API/BD y el extracto de log más pequeño que muestre la falla.
Luego pide algo acotado:
Si usas una plataforma de vibe-coding como Koder.ai (koder.ai), este enfoque de expediente mantiene la sugerencia enfocada. Sus snapshots y rollback también ayudan a probar cambios pequeños de forma segura y volver a una base conocida.
Entrégalo a un desarrollador con experiencia cuando la corrección toque seguridad, pagos, migraciones de datos o cualquier cosa que pueda corromper datos en producción. También entrégalo si el cambio sigue creciendo más allá de un parche pequeño o no puedes explicar el riesgo en palabras sencillas.
Empieza reescribiendo el informe como un script reproducible: quién (rol), dónde (página/flujo), qué entradas exactas (IDs, filtros, payload), qué esperabas y qué viste. Si falta alguna pieza, pide una cuenta de ejemplo y un ID de registro para poder ejecutar el mismo escenario de punta a punta.
Elige un entorno y quédate en él hasta poder reproducir el error. Luego anota la versión/build, flags de feature, configuración, cuenta/rol de prueba y los datos exactos que usaste. Así evitas “arreglar” un problema que solo existe porque tu entorno no coincide con el del reportero.
Haz que ocurra dos veces con los mismos pasos y entradas, y luego elimina todo lo que no sea necesario. Apunta a 3–6 pasos desde un estado limpio con un registro reutilizable o un cuerpo de petición. Si no puedes reducirlo, suele indicar dependencia de volumen de datos, temporización o trabajos en segundo plano.
No cambies nada todavía. Primero ejecuta exactamente los pasos del reportero y anota el primer punto donde tu experiencia difiere (etiqueta de botón distinta, campo que falta, texto de error distinto). Esa primera discrepancia suele ser la pista de la condición real que dispara el error.
Comprueba si los datos realmente cambiaron. Si la API devuelve el valor actualizado pero la UI aún muestra el antiguo, probablemente sea un problema de estado de UI, caché o re-fetch. Si la respuesta de la API está equivocada o la operación nunca se guarda, centra la investigación en la API o BD. Si la fila en la BD no se actualiza (o afecta 0 filas), el problema está en la persistencia o en la condición del WHERE.
Comprueba que al hacer clic se dispare una petición de red y luego inspecciona el payload y el cuerpo de la respuesta, no solo el código de estado. Guarda un timestamp (con zona horaria) y un identificador de usuario para poder emparejar los logs del backend. Un 200 “exitoso” con un body inesperado puede ser tan relevante como un 400/500.
Varía una perilla a la vez: rol, registro (nuevo vs legado), navegador/dispositivo, sesión limpia (incógnito/cache limpio) y red. Las pruebas de una sola variable te dicen qué condición importa y evitan que persigas coincidencias causadas por cambiar varias cosas a la vez.
Cambiar múltiples variables a la vez, probar en un entorno distinto al del reportero e ignorar roles/permisos son las mayores pérdidas de tiempo. Otro error común es arreglar el síntoma superficial en la UI cuando debajo sigue existiendo un error de validación en la API/BD. Siempre vuelve a ejecutar la reproducción exacta tras tu cambio y luego prueba un escenario cercano.
“Hecho” significa: la reproducción mínima original ahora pasa, y además has vuelto a probar un flujo cercano que podría verse afectado. Define la verificación de forma concreta, como una señal visible de éxito, una respuesta HTTP correcta o el cambio esperado en la fila de la BD. Evita “creo que está arreglado” sin volver a ejecutar las mismas entradas en la misma línea base.
Entrega un expediente compacto: pasos mínimos con entradas exactas, entorno/build/flags, cuenta y rol de prueba, esperado vs real, y una prueba (request/response, texto de error o un extracto de log con timestamp). Pide el parche más pequeño que haga pasar la reproducción e incluye un mini plan de pruebas. Si usas Koder.ai, emparejar este expediente con snapshots/rollback ayuda a probar cambios pequeños de forma segura y volver atrás si hace falta.