Informes de fallos accionables: qué incluir para que los errores se solucionen

Qué hace que un informe de fallos sea accionable

La mayoría de los informes de fallos se estancan por una razón simple: la persona que los lee no puede recrear lo que viste. “Se cerró al pulsar el botón” suena claro, pero deja fuera detalles importantes, como qué botón, en qué pantalla estabas antes y qué datos intervenían.

Un informe de fallos accionable no es una historia larga. Es un conjunto conciso de hechos que permite a un ingeniero reproducir el fallo en un intento, o al menos acotarlo a una zona pequeña de la app. El objetivo es hacer el problema repetible, no solo memorable.

Los equipos no técnicos pueden capturar la mayor parte de lo que los ingenieros necesitan sin tocar código. Si puedes describir lo que hiciste, anotar lo que esperabas y copiar algunos identificadores de la app (o de tu herramienta de crashes), puedes ahorrar horas de conjeturas.

Los informes accionables se centran en:

• Acciones específicas, no resúmenes (por ejemplo, “Toqué Guardar en la pantalla Editar perfil después de cambiar el email”)
• Esperado vs real (“Esperaba un mensaje de éxito, apareció una pantalla en blanco y luego la app se cerró”)
• Detalles exactos del entorno (“iPhone 13, iOS 17.2, Wi‑Fi”)
• Identificadores rastreables (un crash ID, request ID o una ventana de tiempo clara para encontrar los logs)
• Consistencia (“Ocurre siempre” vs “solo una vez hasta ahora”)

La precisión importa más que el comentario adicional. Si no estás seguro, dilo. “Creo que me habían cerrado la sesión” todavía es útil, pero debe marcarse como suposición.

Un ejemplo rápido: un tester reporta “fallo en checkout.” Un ingeniero no puede hacer mucho con eso. Pero “El checkout falla después de aplicar el cupón del 10% en una cuenta de invitado, justo después de tocar Pagar” apunta a una ruta e input específicos.

Si tu app fue generada por una herramienta de IA y el comportamiento cambia entre builds, este nivel de detalle importa aún más. Equipos como FixMyMess a menudo ven problemas que solo se reproducen bajo una combinación concreta de build y ajustes, y un buen informe hace eso visible rápidamente.

Los detalles mínimos que debe incluir todo informe

Los ingenieros no pueden arreglar lo que no pueden reproducir. No necesitas lenguaje técnico, pero sí unos detalles exactos que creen un camino directo de “se cayó” a “puedo verlo fallar en mi máquina”.

Empieza con un resumen de una frase que nombre la acción y el lugar donde ocurrió. Por ejemplo: “La app se cerró al tocar ‘Guardar’ en la pantalla de Checkout.” Esa única línea indica dónde mirar y qué estabas haciendo.

A continuación, fija cuándo ocurrió. Una ventana de tiempo suele ser mejor que un único timestamp (por ejemplo, “entre 14:10 y 14:20 PT”), especialmente si alguien debe cotejarlo con logs del servidor. Si el equipo está distribuido, siempre incluye la zona horaria.

Luego captura el entorno básico y lo que viste frente a lo que esperabas, en lenguaje llano. Finalmente, añade la frecuencia. “Cada vez” cambia la prioridad y el enfoque de depuración respecto a “solo una vez”.

Si no sabes qué escribir, usa esta estructura:

• Resumen: qué hiciste y dónde ocurrió el fallo
• Hora: ventana de tiempo y zona horaria
• Dónde: dispositivo/computadora, versión del SO, navegador (si aplica) y la pantalla/página de la app
• Esperado vs real: qué pensabas que pasaría y qué pasó en su lugar
• Frecuencia: una vez, a veces o siempre (y desde cuándo)

Estos cinco ítems llevan menos de un minuto recopilarlos y previenen el ida y vuelta que retrasa las correcciones.

Contexto de usuario sin exponer datos personales

Los ingenieros pueden arreglar fallos más rápido cuando pueden atar un informe a la cuenta y sesión exactas que encontraron el bug. La clave es dar suficiente contexto para reproducir, sin pegar datos personales en tickets o chats.

Usa un identificador estable y no legible en lugar de un nombre o email. Un identificador de usuario hasheado (o un ID interno que no signifique nada fuera de tu sistema) permite al equipo extraer los logs y registros de base de datos correctos manteniendo el informe seguro para compartir. Si tu producto lo soporta, incluye tanto el ID hasheado como el ID de tenant o workspace para facilitar la depuración en apps multi-cuenta.

Si la app muestra un session ID, request ID o correlation ID en algún sitio (a menudo en una pantalla de error, panel de debug o vista de soporte), cópialo exactamente. Un request ID puede señalar a los ingenieros una única llamada fallida, lo cual suele ser más rápido que leer una larga descripción.

Detalles de contexto de usuario que suelen ayudar más:

• Identificador de usuario hasheado (o ID interno de usuario), más workspace/tenant ID si es relevante
• Si el usuario estaba autenticado y su rol (admin, miembro, viewer)
• Estado de la cuenta (cuenta nueva, invitada sin aceptar, prueba expirada, pago fallido)
• Session ID o request ID que muestre la app
• Alcance (una persona, un pequeño grupo o todos)

Si no puedes identificar al usuario exacto, describe el sustituto seguro más cercano: “cuenta nueva creada hoy”, “cuenta existente con 200+ registros” o “admin en un workspace con SSO activado.”

Ejemplo: en lugar de “El dashboard de Jane se cae”, escribe “User hash: 9f3a… Autenticado: sí. Rol: admin. Workspace: 41c… Request ID: req_18b… Solo afecta a este admin; otros miembros pueden abrir el dashboard.” Ese párrafo hace los informes de fallos mucho más accionables.

Información de versión y build que necesitan los ingenieros (incluido el build SHA)

Dos personas pueden “estar en la versión 1.4” y aun así ejecutar código distinto. Por eso los detalles de versión son una parte central de los informes accionables: permiten a un ingeniero recuperar el release exacto que usabas y ejecutar la misma ruta de código.

Empieza por lo que ves en la UI de la app. Muchas apps muestran esto en Ajustes, Ayuda o Acerca de. Incluye la versión de la app y el número de build exactamente como aparece (incluyendo cualquier letra, por ejemplo 1.4.2 (304)). Si el fallo ocurre en una app web, incluye el banner de versión (si se muestra) y la versión del navegador.

Luego viene el identificador más útil: el build SHA (también llamado commit hash). Es la huella única del código que se lanzó. Si tu equipo usa un sistema CI, el SHA suele aparecer en notas de release, salida del pipeline de build o en una pantalla interna de diagnóstico.

También anota de dónde vino el build. “Producción” vs “staging” vs “build de prueba” puede cambiar APIs, datos y permisos. Añade la fecha del release y señala si fue un hotfix. Si esto empezó después de un deploy específico, dilo tan claro como puedas.

Un conjunto compacto de campos que normalmente da a los ingenieros todo lo que necesitan:

• Versión de la app y número de build (tal como se muestra en la UI)
• Build SHA / commit hash
• Canal de release (producción, staging, test)
• Fecha de release y si fue hotfix
• “Se rompió tras el deploy X” (o “iba bien ayer, hoy falla”)

Ejemplo: “El fallo empezó justo después del hotfix del 12 de enero. Estoy en 2.3.1 (718), producción, SHA 9f2c1a7.” Si heredaste una app generada por IA y estos campos no están expuestos en ninguna parte, equipos como FixMyMess pueden añadir un panel de diagnóstico simple para que futuros informes sean más rápidos de completar.

Feature flags y ajustes en tiempo de ejecución que cambian el comportamiento

Un fallo puede ser imposible de reproducir si la app estaba ejecutándose con un conjunto distinto de switches al que prueba el ingeniero. Las feature flags, experimentos y ajustes ocultos a menudo cambian rutas de código, llamadas a API e incluso qué pantallas aparecen.

Cuando envíes informes accionables, captura lo que estaba activo en el momento del fallo, no lo que crees que “normalmente” está activado.

Qué registrar (la versión práctica y rápida)

Registra cualquier cosa que pueda cambiar el comportamiento: feature flags o variantes de experimento activas (nombres y on/off o valor de la variante), contexto de cuenta (región, plan/tier, workspace, rol), entorno (producción vs staging y qué URL base de API usó la app) y estado de los datos (cuenta recién creada, datos demo o una cuenta antigua con registros existentes). También anota condiciones inusuales como red pobre, VPN/proxy, Modo de ahorro de energía o actualización en segundo plano desactivada.

Un pequeño detalle aquí puede explicar por qué solo un cliente ve el fallo. Por ejemplo, una flag “newBillingUI=true” podría estar activada solo para workspaces de la UE en el plan Pro.

Un ejemplo concreto

En lugar de: “Se cuelga al abrir Facturación.”

Incluye: “Se cuelga al abrir Facturación con flags: newBillingUI=on, invoicesV2=variantB. Región del workspace=EU, plan=Pro, rol=Owner. Entorno=Producción, API base URL configurada a api.prod.company.com. La cuenta tiene 3 años de historial de facturas (no es una cuenta nueva). Red: Wi‑Fi de hotel con VPN activada; Modo de ahorro de energía encendido.”

Si tu equipo no puede ver fácilmente las flags, añade una frase sobre dónde las viste (panel de admin, pantalla de debug o herramienta de soporte). Si la app fue construida por una herramienta de IA y los ajustes están dispersos, equipos como FixMyMess suelen comenzar sacando a la superficie estas settings para que futuros informes sean más fáciles de capturar.

Cómo escribir pasos de reproducción que la gente pueda seguir de verdad

Los buenos pasos de reproducción se leen como una receta. Facilitan que otra persona empiece desde el mismo punto, haga las mismas acciones y vea el mismo fallo.

Empieza por escribir el estado en que la app está antes de que ocurra nada. Los pequeños detalles importan: autenticado vs no autenticado, qué workspace/cuenta usaste y la pantalla exacta desde la que empezaste.

Cuando escribas los pasos, usa una acción por línea e incluye inputs reales (ejemplos seguros). “Subir un PDF” suele ser demasiado vago. “Subir un PDF de 24 MB con 180 páginas” le dice al ingeniero qué puede estar provocando problemas de memoria, parseo o timeout.

Un formato que suele funcionar:

1. Punto de inicio: abre la app, inicia sesión como usuario regular y ve a la página Billing.
2. Cambia una cosa: activa la Feature X (si puedes ver flags/settings) y deja todo lo demás por defecto.
3. Realiza la acción: haz clic en “Subir factura” y selecciona un PDF de 25 MB (cualquier muestra no sensible).
4. Momento clave: pulsa “Enviar” y espera a que la barra de progreso llegue al 100%.
5. Condición de paro: la app se cierra al escritorio (o la pestaña del navegador se recarga) en 2 segundos; si se reproduce, anota “ocurre 3/3 veces.”

Añade una frase final que contraste esperado vs real. Ejemplo: “Esperado: mensaje de éxito y la factura aparece en la lista. Real: la app se cierra justo después de Enviar.”

Si heredaste un prototipo generado por IA y los pasos se sienten inconsistentes (funciona una vez y luego falla), dilo. Equipos como FixMyMess suelen encontrar bugs de estado oculto en código generado por IA que solo aparecen tras una secuencia específica.

Adjuntos que ahorran horas (logs, capturas, crash IDs)

Un buen adjunto convierte una conjetura en una solución rápida. Si los ingenieros pueden ver lo que viste y tomar el texto exacto del error, muchas veces pueden reproducir el fallo en minutos en lugar de días.

Empieza con prueba visual. Una captura ayuda, pero una grabación corta de pantalla es mejor porque captura los 10 segundos antes del fallo: el clic que hiciste, el estado de la página y cualquier banner de advertencia o spinner de carga.

También captura texto, no solo fotos de texto. Si aparece un mensaje de error, cópialo exactamente y pégalo en el informe. Detalles pequeños como puntuación, códigos de error y orden de líneas importan.

Adjuntos que suelen ahorrar más tiempo:

• Una captura o grabación corta mostrando los pasos justo antes del fallo
• Texto completo del error copiado exactamente (sin parafrasear)
• Bloque relevante de consola (para apps web), incluyendo las líneas previas al primer error
• Detalles de la red para la petición que falló: endpoint, código de estado y cualquier request ID mostrado
• Crash ID o log del dispositivo desde tu herramienta de reporting de fallos (si la tienes)

Manténlo enfocado. No vuelques 5.000 líneas de logs. Si puedes, copia un pequeño fragmento alrededor del primer error y anota la ventana de tiempo cuando ocurrió el fallo.

Si trabajas con un prototipo generado por IA (de herramientas como Bolt o Replit) y se cuelga de forma impredecible, estos adjuntos son exactamente lo que equipos como FixMyMess usan para diagnosticar la causa real rápidamente, sin adivinar lo que pasó en tu pantalla.

Errores comunes que impiden reproducir

La mayoría de los informes fallidos describen el dolor, no el camino. Los ingenieros avanzan más rápido cuando pueden recrear la situación exacta que causó el fallo.

Algunos hábitos convierten informes potencialmente buenos en callejones sin salida:

• Reportar solo el síntoma (“el login no funciona”) sin los pasos exactos, la pantalla y el esperado vs real.
• Combinar distintos problemas en un mismo informe (un cierre, una pantalla lenta y un botón que falta). Cada problema necesita su propio informe para que alguien reproduzca una cosa a la vez.
• Olvidar los detalles de versión después de un release, hotfix o rollback. Sin número de build o build SHA, los ingenieros pueden depurar el código equivocado.
• Compartir datos personales (emails, teléfonos, tokens de acceso) en lugar de un identificador de usuario hasheado y capturas seguras con campos sensibles ocultos.
• No mencionar feature flags, variantes de experimento o settings en tiempo de ejecución que cambian el comportamiento. Un fallo que ocurre solo en una variante puede parecer aleatorio sin esa nota.

Un ejemplo rápido

Un informe vago: “El checkout falló para un cliente tras el deploy.” Eso no da casi nada a los ingenieros.

Un informe reproducible: “En iOS, build SHA 9f2c..., FeatureFlag: NewCheckout=true, Experiment: PricingTest=B. Usando hashed user ID 3b1a... Tocar Carrito, luego Pagar, cambiar a otra app 10 segundos y volver. La app se cuelga al volver a la pantalla de pago.” Ahora el ingeniero puede casar el código, la configuración y el estado del usuario.

Si tu producto se construyó con una herramienta de IA y la base de código es un desorden, estas lagunas empeoran porque pequeñas diferencias de configuración pueden activar rutas totalmente distintas. Equipos como FixMyMess suelen ver bugs “no reproducibles” desaparecer una vez que los informes incluyen consistentemente info de build, contexto de usuario seguro y las flags activas.

Lista de comprobación rápida antes de enviar

Antes de pulsar enviar, haz una pasada de 60 segundos para asegurarte de que tu informe crea un camino claro para reproducir. Un ingeniero debería poder intentar reproducir el fallo sin necesitar una pregunta adicional.

• Pasos de repro: ¿puede un compañero seguirlos exactamente desde cero, sin huecos tipo “y luego falló”?
• Detalles de versión: ¿incluiste la versión de la app más el build SHA (o commit hash) del build que falló?
• Anclaje de usuario: ¿añadiste un identificador de usuario hasheado (o ID de cuenta hasheado) y una ventana de tiempo (por ejemplo, “entre 14:10 y 14:20 UTC”) para encontrar logs rápido?
• Conmutadores de comportamiento: ¿listaste flags, experimentos, settings de entorno o modos de prueba que estaban activos?
• Evidencia: ¿adjuntaste la prueba más pequeña útil (crash ID, un pequeño extracto de log alrededor del fallo y una captura si aclara el estado)?

Si falta un ítem, añádelo ahora. El build SHA y las feature flags suelen ser la diferencia entre “no reproducible” y una corrección el mismo día.

Una regla práctica para los adjuntos: incluye lo que confirma el estado exacto (pantalla, inputs, toggles) y omite lo grande o no relacionado. Si luchas con una app generada por IA donde los fallos se entrelazan con auth, secretos o arquitectura desordenada, equipos como FixMyMess pueden traducir un informe sólido más una base de código rota en un issue reproducible y una solución verificada con rapidez.

Ejemplo: convertir un informe vago en uno reproducible

Un patrón común es un fallo que aparece justo después de que alguien activa una nueva feature flag. El equipo puede quedarse atascado porque “me falla” no explica qué ruta de código se ejecutó.

Un mal informe (difícil de actuar):

“App se cayó al probar el nuevo checkout. Ocurrió dos veces. Arregladlo por favor.”

El mismo problema como un informe mejorado que un ingeniero puede reproducir rápido:

Title: Crash on Checkout when `checkout_v2` flag is ON

What happened:
- App closes immediately after tapping “Pay” on Checkout

Where:
- iOS app

When:
- 2026-01-19 ~14:12 PT

Steps to reproduce:
1) Sign in
2) Add any item to cart
3) Go to Checkout
4) Ensure feature flag `checkout_v2` = ON
5) Tap “Pay”

Expected:
- Payment confirmation screen

Actual:
- App crashes, returns to home screen

User context (non-PII):
- hashed_user_id: 7c9b1f3a
- account_type: standard

Build info:
- version: 2.8.1 (381)
- build_sha: 3f2a9c1

Runtime settings:
- feature_flags: checkout_v2=ON, payments_sandbox=OFF
- environment: production

Crash info:
- crash_id: iOS-2026-01-19-1412-PT-01933
- last_screen: Checkout

Tres campos hacen la mayor parte del trabajo aquí:

• build_sha (el ingeniero comprueba el commit exacto y los símbolos de ese build)
• feature_flags (el ingeniero ejecuta la misma ruta de código y evita el “me funciona en mi máquina”)
• hashed_user_id (el ingeniero busca en los logs del servidor esa sesión sin exponer datos personales)

Con esos detalles, un ingeniero puede filtrar logs alrededor del timestamp, confirmar el crash_id, verificar qué código flag-ado se ejecutó y localizar la función que falla.

Si la app fue generada por una herramienta de IA y el código es difícil de seguir, equipos como FixMyMess pueden ayudar a diagnosticar y reparar la lógica subyacente rápido, pero el informe aún necesita estas bases para llegar a la causa raíz.

Siguientes pasos: convierte esto en hábito del equipo (y pide ayuda si la necesitas)

La forma más rápida de arreglar bugs es hacer que reportarlos sea aburrido y consistente. Cuando todos usan el mismo formato, los ingenieros dejan de adivinar y comienzan a reproducir.

Convierte tu mejor informe en una plantilla compartida que el equipo pueda reutilizar. Ponla donde la gente ya trabaja (herramienta de tickets, un doc o un formulario). Mantenla corta, pero no sacrifiques los campos que importan.

Establece una regla simple: ningún ticket avanza hasta que los campos mínimos estén completados. Si quieres que se cumpla, hazlo parte del triage, no una sugerencia amable.

Un mínimo práctico para la plantilla:

• Qué pasó y qué esperabas
• Pasos para reproducir (aunque sean “a veces”)
• Entorno: dispositivo, SO, navegador, red
• Info de versión: versión de la app y build SHA
• Conmutadores en tiempo de ejecución: feature flags y settings clave

Una vez exista la plantilla, úsala para detectar patrones. Sigue los fallos repetidos por build SHA y por combinaciones de feature flags. A menudo descubrirás que el mismo fallo está ligado a un único rollout, a una flag concreta o a un build que solo algunos usuarios recibieron.

Ejemplo: soporte ve cinco fallos que parecen no relacionados. Tras añadir build SHA y flags, notas que los cinco ocurrieron en el mismo build con una nueva flag de checkout activada. Ahora ingeniería tiene un objetivo claro y puede reproducir rápidamente.

Si tu app empezó como un prototipo generado por IA y el código es desordenado, los fallos pueden volver porque las causas raíz son más profundas (flows de auth rotos, secretos expuestos, lógica enmarañada). En ese caso, una auditoría enfocada puede ser más rápida que perseguir un fallo tras otro. FixMyMess (fixmymess.ai) ofrece una auditoría de código gratuita y puede remediar problemas recurrentes como auth rota, huecos de seguridad y lógica inestable cuando necesites ayuda experta.