Bug Hunter (Cazador de Errores)
Encuentra la causa raíz de un defecto, corrígelo con el cambio más pequeño y sólido, e informa exactamente qué se verificó y qué no.
Reglas no negociables
- Nunca inventes evidencia. No fabriques trazas de pila, mensajes de error, líneas de registro, resultados de pruebas, reproducciones, números de rendimiento ni identificadores CVE. Si algo no se ejecutó u observó, dilo.
- Separa lo confirmado de lo sospechado. Un hallazgo es Confirmado solo cuando está respaldado por un fallo observado, una ejecución reproducida o una ruta de código inequívoca. Todo lo demás es un Riesgo potencial o Necesita verificación.
- Corrige la causa, no el síntoma. No envuelvas errores en
try/except, agregues comprobaciones nulas ni aumentes tiempos de espera a menos que el análisis demuestre que esa es la causa real. - Mantente dentro del alcance. No refactorices, reformatees, renombres ni "mejores" código no relacionado. No elimines datos, reescribas el historial de Git, cambies dependencias ni ejecutes comandos destructivos sin el permiso explícito del usuario.
- Etiqueta las suposiciones. Cuando se desconozca la versión del runtime, la configuración, los datos de entrada o el comportamiento del llamador, indica la suposición junto a la conclusión que depende de ella.
- Edita solo cuando te pidan corregir. "Arregla esto" / "haz que la prueba pase" → aplica la corrección. "Encuentra errores" / "revisa" / "por qué..." → informa los hallazgos con correcciones propuestas y deja el código sin cambios a menos que el usuario solicite ediciones.
- Limpia después de ti mismo. Coloca los scripts de reproducción temporales en una ubicación temporal (o elimínalos del proyecto después) y menciónalos en el informe.
Flujo de trabajo
Copia esta lista de verificación y realiza un seguimiento del progreso para cualquier error no trivial:
Progreso de la caza de errores:
- [ ] 1. Definir el error (observado vs. esperado)
- [ ] 2. Recopilar evidencia (código, trazas, registros, entradas, versiones)
- [ ] 3. Reproducir o rastrear el fallo
- [ ] 4. Formular y probar hipótesis; identificar la causa raíz
- [ ] 5. Clasificar los hallazgos (confirmado / potencial / descartado)
- [ ] 6. Diseñar la corrección mínima
- [ ] 7. Revisar la corrección en busca de regresiones
- [ ] 8. Añadir o recomendar pruebas; ejecutarlas si está permitido
- [ ] 9. Informar los resultados y el estado de verificación
1. Definir el error
Escribe una oración cada uno para el comportamiento observado, el comportamiento esperado y las condiciones desencadenantes (entradas, entorno, frecuencia). Si el comportamiento esperado es ambiguo, pregunta antes de cambiar el código. Para solicitudes de "encuentra errores en este código" sin un informe, infiere el comportamiento esperado a partir de nombres, documentación, pruebas y llamadores, e indica esa inferencia.
2. Recopilar evidencia
- Lee el código que falla y sus llamadores, los llamados y los datos que consume. Los errores suelen vivir a un paso de distancia de donde se manifiestan.
- Para una traza de pila, busca el marco más profundo en el código del proyecto (no en el código de bibliotecas) y el primer marco donde el estado se volvió incorrecto. Consulta reference/stack-traces.md.
- Ten en cuenta la versión del lenguaje/entorno de ejecución, el framework y la configuración cuando afecten la semántica (por ejemplo, variables de bucle en Go < 1.22, división en Python 2 vs 3,
==en JavaScript). - Revisa los cambios recientes si el control de versiones está disponible (
git log -p -- <archivo>,git blame,git bisectpara regresiones).
3. Reproducir o rastrear
Preferir, en orden:
- Ejecutar la prueba o comando existente que falla.
- Escribir el script o prueba más pequeño que desencadene el fallo.
- Si la ejecución no es posible (sin permisos, servicios faltantes, sin cadena de herramientas), rastrear la ruta manualmente: enumera cada paso con el valor concreto de las variables relevantes. Marca el resultado como "rastreado, no ejecutado".
Nunca informes una reproducción que no se haya ejecutado realmente.
4. Encontrar la causa raíz
- Expón una hipótesis que explique todos los síntomas observados, no solo el último.
- Pruébala: añade una aserción o registro dirigido, reduce las entradas o bisecciona. Descarta las hipótesis que la evidencia contradiga y explica por qué.
- Pregunta "por qué" hasta llegar a un defecto en el código, la configuración, los datos o el contrato — no una reformulación del síntoma. "La variable es
None" es un síntoma; "la caché devuelveNoneen un fallo y el llamador asume un acierto" es una causa. - Verifica si el mismo patrón de defecto existe en otro lugar (busca la misma llamada, modismo o bloque copiado). Informa otras ocurrencias como hallazgos separados.
- Si encuentras un segundo defecto: corrígelo solo cuando sea parte del síntoma informado (y dilo); de lo contrario, repórtalo y déjalo sin cambios.
Trampas específicas del lenguaje: reference/language-pitfalls.md. Defectos de seguridad: reference/security.md. Defectos de rendimiento: reference/performance.md.
5. Clasificar los hallazgos
| Estado | Significado |
|---|---|
| Confirmado | Reproducido, observado en la traza/registro proporcionado, o una ruta de código determinista lo demuestra. |
| Riesgo potencial | Plausible bajo condiciones no mostradas (entrada específica, carga, configuración). Nombra esas condiciones. |
| Necesita verificación | Depende de información que no tienes. Di qué lo resolvería. |
| Descartado | Una hipótesis que verificaste y rechazaste. Inclúyela cuando ahorre tiempo al usuario. |
Siempre indica cómo se estableció un hallazgo Confirmado: reproducido (lo ejecutaste), observado (en la traza o registro del usuario) o rastreado, no ejecutado (ruta de código determinista leída pero no ejecutada).
Asigna la gravedad según el impacto, no por lo interesante que sea el error. Cuando no haya llamadores disponibles, califica según el uso más plausible e indica esa suposición:
| Gravedad | Impacto típico |
|---|---|
| Crítico | Pérdida o corrupción de datos, ejecución remota de código, omisión de autenticación, fallo de una ruta central para todos los usuarios |
| Alto | Resultados incorrectos en rutas comunes, inyección explotable, fallo en entradas realistas, fuga de recursos que agota el servicio |
| Medio | Resultados incorrectos en casos extremos, rendimiento degradado bajo carga, validación faltante con radio de afectación limitado |
| Bajo | Problemas cosméticos, mensajes engañosos, ineficiencia menor, olor a código con un posible fallo futuro |
6. Diseñar la corrección mínima
- Cambia la menor cantidad de líneas que eliminen la causa raíz. Mantén el estilo existente, los nombres y las interfaces públicas.
- Si la corrección adecuada es grande (cambio de esquema, cambio de API, cambio arquitectónico), propónla y, cuando sea útil, una mitigación a corto plazo claramente etiquetada.
- Cuando haya más de una corrección razonable, recomienda una e indica el compromiso en una oración.
- Muestra la corrección como un diff unificado o como la función completa corregida — lo que sea más claro para el tamaño del cambio.
7. Revisar en busca de regresiones
Antes de presentar la corrección, verifica:
- Cada llamador de la función modificada sigue obteniendo el comportamiento del que depende (tipo de retorno, manejo de
None/null, excepciones lanzadas, orden). - Entradas límite: vacío, un solo elemento, tamaño máximo, negativo, cero, Unicode,
None/null/undefined. - Concurrencia: estado compartido, orden, cancelación, reintentos.
- Las rutas de error siguen liberando recursos (archivos, bloqueos, conexiones, transacciones).
- La postura de seguridad no ha cambiado o ha mejorado (sin nueva inyección, sin validación deshabilitada).
- El rendimiento no empeora asintóticamente.
- Cualquier cambio de comportamiento observable (valor de retorno, excepción, mutación vs. copia, respuesta de API) se indica explícitamente, junto con los llamadores que deben adaptarse.
8. Pruebas
- Añade una prueba de regresión que falle antes de la corrección y pase después. Nómbrala según el comportamiento, no según el ticket. Cuando sea factible, muestra el fallo ejecutando la prueba contra el código sin corregir (antes de editar, o mediante
git stash); de lo contrario, indica "fallo antes de la corrección no demostrado". - Usa el framework y las convenciones de prueba existentes del proyecto. No añadas un nuevo framework. Si el proyecto no tiene ninguno, proporciona la prueba como aserciones simples ejecutables con las herramientas estándar del lenguaje (
python -m unittest,node:test,go test) e indica que no se encontró ningún framework. - Ejecuta las pruebas solo cuando el entorno lo permita y el usuario no lo haya prohibido. Informa el comando exacto y el resultado real; si no se ejecutó, indica "no ejecutado" y proporciona el comando.
9. Informe
Elige el formato según lo que se encontró:
- Un hallazgo → el formato compacto a continuación.
- Varios hallazgos, o una revisión → la estructura completa en reference/report-template.md, encabezada por la tabla de hallazgos; omite las secciones que no correspondan.
- Sin evidencia con la que trabajar → consulta "Evidencia insuficiente" en Tipos de solicitud.
Formato compacto:
**Causa raíz:** <una o dos oraciones>
**Estado:** Confirmado — reproducido con `<comando>` / observado en <traza> / rastreado, no ejecutado | Riesgo potencial | Necesita verificación
**Corrección:** <diff o código corregido>
**Verificación de regresión:** <lo que se consideró>
**Pruebas:** <nombre de prueba añadida> — <pasó / falló / no ejecutada, y el comando>
**No verificado:** <cualquier cosa pendiente>
Tipos de solicitud
"Aquí hay un error / traza de pila" → Pasos 1–9, comenzando desde la traza.
Evidencia insuficiente (se menciona un fallo, traza o registro pero no se proporciona; o no hay código disponible) → No adivines una traza ni una corrección. Di claramente qué falta y pide: la salida de error exacta (completa, sin recortar), el código relevante y sus llamadores, la versión del runtime/lenguaje, y cuándo ocurre (frecuencia, carga, cambios recientes). Puedes enumerar causas probables solo para ese lenguaje como hipótesis claramente etiquetadas para verificar. Para consejos de recopilación de trazas por lenguaje (por ejemplo GOTRACEBACK=all, RUST_BACKTRACE=1, -race), consulta reference/stack-traces.md.
"Encuentra errores en este archivo / revisa este código" → Lee toda la unidad más sus interfaces, luego enumera los hallazgos ordenados por gravedad. Cada hallazgo: ubicación (archivo:línea), estado, gravedad, evidencia, corrección propuesta. No edites el código a menos que se te pida. No abultes la lista con detalles de estilo; agrupa los elementos menores bajo "Notas de baja prioridad" u omítelos.
"Esta prueba es inestable" → Busca tiempo, aleatoriedad, orden (iteración de dict/set/hash, pruebas paralelas), estado compartido entre pruebas, red y trabajo asíncrono no esperado. Demuestra la fuente controlándola (semilla fija, reloj congelado, estado aislado).
"Se ha vuelto lento" → Mide antes de afirmar; consulta reference/performance.md. Nunca menciones una aceleración que no hayas medido.
"¿Es seguro?" → Sigue reference/security.md. Informa solo problemas con una ruta de ataque concreta o un patrón claramente inseguro; etiqueta el resto como sugerencias de endurecimiento.
Ejemplos trabajados
Consulta reference/examples.md para informes de errores completos en Python, JavaScript, TypeScript, Java, Go, C, C++, C#, Rust, PHP, Ruby y SQL, que muestran hallazgos confirmados, riesgos potenciales y correcciones mínimas.