Definición de "hecho" para correcciones de errores: una lista de verificación práctica

Qué significa “hecho” para una corrección de errores (en palabras sencillas)

Un error no está resuelto solo porque el código compila o porque funciona en una sola máquina. “Arreglado en mi máquina” suele significar que la prueba fue demasiado limitada, la configuración era distinta o se pasó por alto un caso límite. Los usuarios reales no usan exactamente tu navegador, tus datos, tu red o tus permisos.

Cerrar un ticket demasiado pronto es la forma en que problemas pequeños se convierten en grandes: suben los tickets de soporte, los compañeros dejan de confiar en las versiones y los parches rápidos se acumulan sobre otros parches rápidos. El costo real casi nunca es el error original. Es el tiempo que se gasta reaprendiendo el mismo problema y limpiando el desastre.

Para una corrección de errores, “hecho” debería significar cuatro cosas: verificado, seguro, observable y explicable.

• Verificado: puedes reproducir el error de forma confiable y puedes demostrar que ya no ocurre.
• Seguro: consideraste pérdida de datos, seguridad y efectos secundarios no deseados.
• Observable: sabes qué vigilar después del lanzamiento y qué justificaría un rollback.
• Explicable: otra persona puede leer el ticket y entender qué pasó, qué cambió y por qué.

Un ejemplo simple: el total del checkout está mal solo para usuarios recurrentes con cupones antiguos. Si pruebas solo con una cuenta nueva, no “arregas” nada para las personas realmente afectadas.

Antes de tocar el código: confirma el bug y su impacto

Muchos “arreglos rápidos” fallan porque el equipo arregla lo incorrecto. Separa lo que el usuario ve (el síntoma) de lo que crees que está roto (la causa). El síntoma es un hecho. La causa es una suposición hasta que la pruebas.

Anota el impacto antes de abrir el editor. Si este bug ocurre una vez al mes para un usuario, lo manejarás distinto que un bug que bloquea registros hoy. La severidad no es “qué tan grave suena”. Es cuántas personas están afectadas, con qué frecuencia y qué no pueden hacer.

Captura el contexto exacto. Muchos bugs son reales solo en un entorno específico: cierta versión de navegador, un dispositivo móvil, una base de datos de staging o una nueva release. Si no puedes decir dónde ocurre, no puedes afirmar con confianza que esté arreglado.

Un checklist rápido previo al código que puedes pegar en un ticket:

• Síntoma: qué ve el usuario, en sus palabras
• Alcance: quién está afectado y con qué frecuencia
• Entorno: versión de la app, dispositivo, navegador/SO y tipo de cuenta
• Comportamiento esperado: qué debería pasar en su lugar
• Enunciado del problema en una frase: “Cuando X, ocurre Y, pero debería ocurrir Z.”

Ejemplo: un fundador dice “el login está roto”. Lo reproduces y descubres que solo falla en Safari después de un restablecimiento de contraseña. Eso cambia el trabajo. No estás “arreglando el login”, estás arreglando un flujo específico de sesión o cookies.

Pasos de reproducción que realmente reproducen (una plantilla simple)

Un informe de bug solo sirve si otra persona puede provocar el error. Si tus pasos de repro solo funcionan para quien lo encontró, es difícil arreglarlo y aún más difícil confirmar que ya no ocurre.

Escribe los pasos como si un compañero nuevo los siguiera sin preguntar. La clave es el estado inicial: quién es el usuario, qué datos existen y qué entorno usaste.

Una plantilla simple de repro

Usa esta plantilla y complétala con detalles reales (no con marcadores):

Title: \u003cshort, specific\u003e
Environment: \u003cprod/staging/local\u003e, \u003cbrowser/app version\u003e, \u003cdevice\u003e
Starting state: \u003clogged in/out\u003e, \u003caccount role\u003e, \u003csample record id\u003e, \u003cfeature flags\u003e
Steps to reproduce:
1) ...
2) ...
3) ...
Expected result: ...
Actual result: ...
Evidence: \u003cerror message\u003e, \u003clog snippet\u003e, \u003cscreenshot description\u003e
Frequency: \u003calways / 3 out of 10\u003e, Triggers: \u003conly after refresh, only on slow network\u003e

Cuando puedas, incluye el texto exacto del error. “El login falla” es vago, pero “400: invalid_grant después del restablecimiento de contraseña” le da al que arregla una pista real.

Si el problema es intermitente, dilo y describe qué parece provocarlo. Menciona tiempos, tipo de dispositivo, extensiones del navegador o cualquier cambio reciente (usuario nuevo, datos importados, plan actualizado).

Haz una comprobación de sentido dando tus pasos a otra persona. Si no pueden reproducir en 5 minutos, el informe necesita otra pasada.

Criterios de aceptación: cómo sabrás que está arreglado

Los criterios de aceptación son la respuesta compartida a: “¿Qué debe pasar después de que lo publiquemos?” Para correcciones de errores, convierten “creo que está arreglado” en “podemos demostrar que está arreglado”.

Describe cómo se ve lo “bueno” en términos sencillos y comprobables. Vincúlalo al resultado del usuario, no a la implementación. Ejemplo: “El usuario puede iniciar sesión con la contraseña correcta y llega al tablero en menos de 2 segundos.”

Luego señala los casos límite que a menudo se pasan por alto: estados vacíos, timeouts, entradas inválidas, reintentos y fallos parciales.

Un checklist simple que puedes copiar:

• El camino principal funciona de extremo a extremo
• Se manejan los casos límite conocidos (entrada vacía, valores inválidos, red lenta, reintento)
• No hay errores nuevos en logs ni advertencias nuevas en la UI para el mismo flujo
• El comportamiento de la UI es claro (mensajes, estados de botones, indicadores de carga, redirecciones)
• Los datos se mantienen correctos (sin duplicados, sin escrituras parciales, sin eliminaciones sorpresa)

Añade non-goals para evitar que el alcance se desborde. Ejemplo: “No cambiaremos la política de contraseñas en esta corrección” o “No rediseñamos la página de login, solo corregimos el manejo de errores”.

Si la corrección cambia texto o comportamiento, escríbelo. “Contraseña incorrecta” vs “Email no encontrado” no es solo redacción. Puede cambiar la carga de soporte y el riesgo de seguridad.

Si es posible, obtén un acuerdo rápido del solicitante. Una confirmación de 2 minutos ahorra un día de rehacer.

Un flujo paso a paso para cerrar un bug de forma segura

Un buen cierre tiene menos que ver con el cambio de código y más con demostrar que el bug desapareció sin crear uno nuevo.

1. Reproducir y capturar evidencia. Captura pantalla, texto exacto del error y el entorno (versión de la app, navegador/dispositivo, rol de usuario, estado de feature flags). Si no puedes reproducir, mejora el informe antes de suponer.

2. Aislar la causa más pequeña probable. Encuentra la condición que cambia el comportamiento (una entrada, un estado de cuenta, una respuesta de API). Esto evita arreglos que “funcionan” por accidente.

3. Hacer el cambio mínimo seguro. Evita refactorizaciones durante una corrección salvo que el desorden sea la causa. Los cambios pequeños son más fáciles de revisar, probar y revertir.

4. Verificar en dos lugares. Prueba localmente y luego en un entorno limpio que coincida lo más posible con producción.

Un checklist rápido para cerrar el ticket:

• Repro confirmado y evidencia guardada
• Causa raíz indicada en una frase
• Cambio mínimo realizado (y por qué es seguro)
• Verificado localmente y en un entorno limpio
• Notas añadidas: qué cambió, qué no cambió y áreas de riesgo

Finalmente, añade notas de despliegue y monitoreo: cómo desplegar con seguridad, qué métricas o logs deben mejorar y qué significaría un rollback (por ejemplo, un pico de errores 500 o fallos de login en la primera hora).

Tests: qué añadir, qué volver a ejecutar, qué documentar

Un bug no está realmente resuelto hasta que las pruebas cuentan la misma historia que tus pasos de repro. Procura dejar al menos una comprobación automatizada que fallaría antes del arreglo y ahora pase.

Añade o actualiza una prueba que coincida con la falla real. Mantenla pequeña y enfocada para que siga siendo legible y no se vuelva frágil. Cubre el camino feliz y luego añade un caso límite que represente cómo se coló el bug (campo faltante, problema de timing, caché obsoleta, configuración rara de usuario).

Después de que la prueba dirigida pase, haz una pequeña regresión en los flujos cercanos que pudiste tocar:

• El recorrido principal de usuario que incluye el código cambiado
• Un flujo adyacente (por ejemplo, registro si arreglaste login)
• Una verificación básica de permisos (autorizado vs no autorizado)
• Para arreglos de UI: verificar en dos navegadores/dispositivos que realmente soportas
• Para arreglos de backend: probar una entrada mala que deba fallar de forma segura

Documenta qué ejecutaste y qué no. Si aceptas una brecha de pruebas, nómbrala y explica por qué (tiempo, herramientas, fixtures faltantes, requisitos poco claros), además de qué la detectaría luego (alerta de monitoreo, tarea de seguimiento, checklist manual).

Ejemplo: si un arreglo de login implicó parseo de tokens, añade una prueba para un token válido y otra para un token malformado que debe devolver un error limpio sin registrar secretos.

Chequeos de seguridad: riesgos de datos y seguridad a descartar

Un bug puede estar “arreglado” y aun así crear un problema mayor: una filtración de datos, una omisión de permisos o logs llenos de información privada. Esta es la parte que la gente se salta cuando tiene prisa.

Revisa lo que cambiaste respecto a entradas, auth y cualquier cosa que toque la base de datos. Muchos incidentes provienen de ediciones pequeñas como “añadir un parámetro” o “loggear más detalles para depurar”.

Antes de marcar el ticket como hecho:

• Secretos: confirma que no se añadieron API keys, tokens o credenciales al código, config, mensajes de error o bundles del cliente.
• Manejo de entradas: valida y sanea entradas, especialmente todo lo que se use en consultas, filtros o sorting. Usa patrones de consulta seguros para evitar SQL injection.
• Auth y permisos: revisa que la ruta arreglada siga exigiendo login y cheques de rol (y que el manejo de errores no los omita accidentalmente).
• Logs: asegúrate de que los logs no incluyan contraseñas, tokens de sesión, enlaces de restablecimiento o datos personales. Si necesitas contexto, registra un ID, no el valor crudo.
• Casos de abuso: si cambió un endpoint o flujo, considera límites de tasa y ataques por fuerza bruta (login, restablecimiento de contraseña, códigos promocionales, OTPs).

Un ejemplo concreto: arreglas un bug de login cambiando la respuesta de error para incluir “detalles útiles” (como si existe el email). Eso puede permitir enumeración de cuentas. Prefiere un mensaje genérico y mantén los detalles internamente.

Hazte unas preguntas finales antes de cerrar:

• ¿Podría este cambio exponer datos al usuario equivocado?
• ¿Podría facilitar adivinar cuentas, tokens o contraseñas?
• ¿Podrían los nuevos logs filtrar algo sensible?
• ¿Podría un bot golpear esto más rápido que un humano?

Notas de despliegue: qué escribir para que las release no sorprendan a nadie

Las notas de despliegue son el “aviso” que convierte un cambio de código en un lanzamiento seguro. Permiten que alguien que no trabajó en el bug entienda qué cambió, cómo se despliega y qué hacer si algo va mal.

Empieza con un resumen corto para lectores no técnicos: qué estaba roto, qué notarán los usuarios ahora y quién está afectado. Si el bug tocó facturación, login o permisos, dilo claramente.

Luego captura los puntos de riesgo en tiempo de deploy:

• Cambios de config (nueva env var, valor cambiado, rotación de secret)
• Migraciones de DB (qué se ejecuta, cuánto puede durar)
• Feature flags (nombre, estado por defecto, quién puede alternarlo)
• Plan de rollout (todo a la vez, canary, faseado por % o región)
• Plan de rollback (qué revertirás y cómo verificarás)

Sé específico sobre los triggers de rollback. “Revertir ahora” debe significar algo observable, como un pico de fallos de login, un aumento de tickets de soporte o un error nuevo claro en logs. Anota si el rollback es seguro con cualquier migración (algunas cambios de esquema no son fácilmente reversibles).

También lista cambios de cara al cliente, aunque sean pequeños: texto en la UI, emails, notificaciones o mensajes de error. Soporte depende de eso.

Ejemplo: “Arreglo de login mejora el manejo de sesiones para usuarios legacy en Safari. Sin cambios en BD. Añadida una env var para timeout del proveedor de email. Rollout: 10% por 30 minutos, luego 100% si el éxito de sign-in se mantiene. Rollback si los errores de sign-in suben por encima del baseline.”

Después del envío: qué monitorear y por cuánto tiempo

Un bug no está hecho cuando se mergea el código. Está hecho cuando el cambio se comporta en el mundo real, con tráfico real.

Establece una ventana de vigilancia para cada release. Para arreglos de bajo riesgo, 2 a 4 horas puede ser suficiente. Para cualquier cosa que toque auth, pagos o datos, planifica 24 a 72 horas. Nombra a un responsable para la ventana (no “el equipo”) y asegúrate de que pueda revertir o hotfixear si hace falta.

Céntrate en señales que muestren el dolor del cliente rápido:

• Tasa de errores y principales errores nuevos (por endpoint o pantalla)
• Latencia y timeouts (p95 suele decir más que promedios)
• Fallos de sign-in y fallos en restablecimiento de contraseña
• Fallos de pago y abandonos en checkout
• Tickets de soporte y quejas de usuarios (cuentan como monitoreo)

Define umbrales que desencadenen acción antes de lanzar, para que no haya debate después. Ejemplos: “fallos de login x2 sobre el baseline durante 10 minutos” o “aparece un error nuevo en el top 5”. Empareja alertas con una respuesta simple: investigar, revertir o pausar el rollout.

También vigila cambios silenciosos pero peligrosos: menos sign-ins completados, menos proyectos creados, más reintentos. Eso puede significar que el bug se movió en vez de desaparecer.

Documenta lo que comprobaste y el resultado: ventana temporal, dashboards/logs revisados, picos vistos y la decisión final.

Trampas comunes que hacen que los bugs “arreglados” vuelvan

Los bugs repetidos casi nunca son mala suerte. Ocurren cuando un arreglo se publica sin la prueba y comunicación que convierte un cambio en un resultado fiable.

Un fallo común es cerrar el ticket sin una repro limpia y sin criterios de aceptación claros. Si no puedes mostrar el bug a demanda, no puedes estar seguro de que desapareció ni de que arreglaste lo correcto.

Otro es arreglar el síntoma y saltarse la causa raíz. Ejemplo: añadir un botón de reintento para una petición que falla cuando el problema real es un token expirado que nunca se refresca. El reintento oculta el bug y acostumbra a los usuarios a seguir clicando.

Las trampas que con más frecuencia revierten un arreglo:

• No hay pasos reproducibles o comprobaciones vagas de “funciona para mí”
• No se añadió una prueba (o se añadió la prueba incorrecta), de modo que un cambio posterior reintroduce el bug en silencio
• Un “arreglo pequeño” que cuela un gran refactor, aumentando el riesgo y dificultando la revisión
• Omitir las notas de despliegue, de modo que soporte y compañeros no saben qué cambió
• Verificar solo el camino feliz, no un entorno realista

Ese último punto merece atención extra. Un arreglo puede pasar localmente pero fallar en staging por datos reales, vars faltantes, caching o settings de auth distintos. Prueba siempre con una cuenta nueva, una sesión de navegador limpia y el dispositivo más lento o antiguo que puedas probar razonablemente.

Ejemplo: cerrar un bug de login sin romper producción

Escenario: tras una actualización generada por IA, algunos usuarios reportan que el sign-in falla. Funciona para el desarrollador, pero no para clientes reales.

Malos pasos de repro se ven así: “El login está roto a veces.” Eso desperdicia horas porque nadie puede ver la falla de forma fiable.

Buenos pasos de repro son específicos y repetibles:

1. Usa un usuario existente creado antes del último release.
2. Cierra sesión y luego intenta entrar en mobile Safari.
3. Introduce email y contraseña correctos.
4. Observa: después de enviar, la página se recarga y sigues desconectado (no se muestra error).

Los criterios de aceptación deben ser igual de claros. Malo: “Los usuarios pueden entrar de nuevo.” Mejor: “El usuario llega al dashboard, recibe una cookie de sesión y permanece conectado tras un refresh. Las contraseñas incorrectas siguen mostrando el mismo mensaje de error que antes.”

Para pruebas, añade una comprobación enfocada y vuelve a ejecutar una regresión:

• Añade una prueba de integración para el flujo de sign-in (credenciales correctas crean una sesión y devuelven éxito).
• Comprobación de regresión: restablecimiento de contraseña, logout y sign-in en el mismo navegador que fallaba.

Las notas de despliegue pueden ser cortas pero concretas: “Arreglo de manejo de sesiones para usuarios legacy en Safari. Sin cambios en BD. Si aparecen problemas, volver a la build anterior e invalidar sesiones.” Después de publicar, vigila la tasa de errores de login, la creación de nuevas sesiones y tickets de soporte por 24 a 48 horas.

El ticket está realmente cerrado cuando el bug se reproduce antes del arreglo, no se reproduce después, las pruebas cubren la falla y las notas de despliegue dicen qué cambió y qué vigilar.

Próximos pasos: haz esto por defecto y pide ayuda cuando la necesites

Haz que esto sea una costumbre por defecto. Elige un lugar donde viva cada bug (tu plantilla de tickets, un doc compartido o un formulario) y pega una página con la “definición de hecho” para que nadie tenga que memorizarla.

Haz un chequeo corto con el equipo para alinear qué significa “hecho”. Las diferencias silenciosas importan: una persona piensa “repro + arreglo” es suficiente, otra espera pruebas, notas de despliegue y un plan de vigilancia poslanzamiento. Acordarlo una vez evita reaperturas.

Prueba la checklist en las próximas tres correcciones y ajústala según lo que se sintió pesado o confuso. Mantenla corta, pero no negociable.

Un inicio simple que puedes copiar en tu plantilla de bug:

• Pasos de repro confirmados (y guardados), además de esperado vs actual
• Criterios de aceptación escritos en lenguaje sencillo
• Pruebas añadidas o actualizadas, y pruebas clave existentes re-ejecutadas
• Notas de despliegue preparadas (riesgo, a quién notificar, plan de rollback)
• Plan de vigilancia poslanzamiento (qué monitorear y por cuánto tiempo)

Si los bugs siguen reabriéndose incluso siguiendo esto, el problema raíz suele ser arquitectónico o de seguridad, no una sola línea de código. Si heredaste una base de código generada por IA de herramientas como Lovable, Bolt, v0, Cursor o Replit, FixMyMess (fixmymess.ai) puede hacer una auditoría de código gratuita para localizar problemas como autenticación rota, secretos expuestos o lógica enmarañada antes de tu siguiente release.