1396. Identidad de la lección
Esta lección establece el vocabulario necesario para razonar desde un fallo visible hasta una explicación comprobable. Continúa después de 3.15 L2 — Crear una verificación centrada en resultados, donde construiste una verificación que produce evidencia útil.
1397. Objetivo de aprendizaje
Después de esta lección, puedes separar la observación del supuesto en un reporte de bug y etiquetar el síntoma, las hipótesis, los mecanismos y la posible causa raíz que deben comprobarse.
1398. Por qué importa
Un reporte que dice “el sistema de colisiones está roto” mezcla lo ocurrido con una explicación que podría ser incorrecta. Esa mezcla dirige el debugging hacia un subsistema supuesto en lugar de dirigirlo hacia la evidencia. Un vocabulario causal claro te ayuda a describir el fallo con precisión, dar instrucciones fiables a un asistente de IA sin presentar conjeturas como hechos y elegir la siguiente verificación diagnóstica. El objetivo no es declarar una causa raíz de inmediato, sino conservar el recorrido desde la evidencia hasta la explicación.
1399. Conocimientos previos
Debes poder ejecutar o inspeccionar una verificación de producción centrada en un resultado, como la de 3.15 L2 — Crear una verificación centrada en resultados. También debes conocer la práctica de preparar una verificación, actuar, observar el resultado y diagnosticar a partir de la evidencia. Esta lección no requiere editar el proyecto.
1400. Concepto central
Un reporte de bug útil distingue seis capas relacionadas:
| Capa | Significado | Ejemplo de redacción |
|---|---|---|
| Síntoma | La manifestación de un fallo que puede percibir una persona o un sistema | “La puerta permanece cerrada.” |
| Observación | El registro de un síntoma concreto bajo condiciones indicadas y con evidencia directamente disponible | “Después de pulsar Interactuar junto a la puerta, la puerta permaneció cerrada.” |
| Supuesto | Una interpretación no verificada presentada como un hecho | “El código de interacción no se está ejecutando.” |
| Hipótesis | Una explicación propuesta y comprobable que predice evidencia capaz de respaldarla o refutarla | “La comprobación de distancia podría estar usando un umbral incorrecto.” |
| Mecanismo | El proceso causal que conecta una condición con el resultado observado | “La comparación de distancia rechaza la interacción antes de ejecutar la orden de apertura.” |
| Causa raíz | La condición subyacente que, al corregirse, evita que el fallo se repita en este contexto | “El umbral de interacción está configurado por debajo del rango de activación previsto.” |
Un síntoma indica cómo se manifiesta el fallo. Una observación convierte ese síntoma en evidencia delimitada al registrar las condiciones, la acción y el resultado directamente disponible. Por ejemplo, “la puerta permanece cerrada” es un síntoma; “después de pulsar Interactuar junto a la puerta, la puerta permaneció cerrada” es una observación.
Estas capas están relacionadas, pero no son intercambiables. Una observación es evidencia. Una hipótesis es una explicación propuesta. Un mecanismo describe cómo esa explicación produciría el resultado. Una causa raíz es una condición más profunda y accionable, no simplemente la etiqueta técnica que suena más específica.
Un mismo síntoma puede tener varios mecanismos posibles. “El personaje no se mueve” podría deberse a una entrada ausente, una regla de movimiento bloqueada, un estado congelado o un problema de presentación que oculta el movimiento. No elijas entre esas explicaciones hasta que una verificación las distinga.
1401. Modelo mental
Usa la cadena S-O-S-H-M-C:
Síntoma → Observación → Supuesto que debes cuestionar → Hipótesis → Mecanismo → Posible causa raíz que debes verificar
Cada paso plantea una pregunta diferente:
- Síntoma: ¿Cómo se manifiesta el fallo para una persona o para un observador del sistema?
- Observación: ¿Qué ocurrió exactamente, bajo qué condiciones y qué evidencia está disponible de forma directa?
- Supuesto: ¿Qué estoy dando por cierto sin evidencia?
- Hipótesis: ¿Qué explicación comprobable podría dar cuenta de la observación y qué evidencia podría respaldarla o refutarla?
- Mecanismo: ¿Mediante qué secuencia produciría esa explicación el resultado?
- Posible causa raíz: ¿Qué condición subyacente podría requerir una corrección y se encuentra respaldada, refutada o todavía sin verificar?
Las flechas no significan que toda investigación avance en línea recta. Una verificación puede descartar una hipótesis y obligarte a formular otra. El modelo protege la frontera entre lo que sabes y lo que estás proponiendo.
1402. Ejemplo concreto
Imagina que una prueba produce este reporte:
“El sistema de objetos recogibles está roto. El jugador pasa sobre la llave, pero la puerta no se abre porque el disparador de recogida no se activa.”
Sepáralo antes de hacer debugging:
- Síntoma: La puerta permanece cerrada después de que el jugador encuentra la llave.
- Observación: En la prueba preparada, el jugador se superpuso con la llave visible; después caminó hasta la puerta y esta permaneció cerrada.
- Supuesto: El disparador de recogida no se activó.
- Hipótesis: La llave no quedó registrada como recogida, o la puerta está comprobando una condición de inventario diferente.
- Mecanismo que debe comprobarse: La superposición podría actualizar el estado visual de la llave sin actualizar el valor de inventario que lee la puerta.
- Posible causa raíz: Los sistemas de recogida y de la puerta podrían usar identificadores diferentes para el mismo objeto.
- Estado actual de la evidencia: Sin verificar; la observación no muestra los identificadores utilizados por los dos sistemas.
- Evidencia necesaria: Registrar, durante la misma prueba preparada, el identificador escrito al recoger la llave y el identificador leído por la puerta.
El reporte revisado no afirma que la diferencia entre identificadores esté demostrada. Registra la manifestación, delimita la observación, hace visible el supuesto y propone un mecanismo y una posible causa raíz que pueden evaluarse mediante una verificación enfocada.
1403. Error común
El error común es tratar el primer nombre plausible de un subsistema como si fuera la causa raíz. Frases como “la física está rota”, “el evento no es fiable” o “la IA generó código incorrecto” son supuestos amplios, no diagnósticos. No indican qué se observó, qué condición estaba presente ni qué secuencia causal conecta esa condición con el fallo. Sustitúyelas por una observación delimitada y una hipótesis que prediga evidencia capaz de respaldarla o refutarla.
1404. Práctica guiada
Reescribe el siguiente reporte usando la cadena S-O-S-H-M-C:
“El sistema de salud está mal. El jugador muere al instante porque el evento de daño se ejecuta dos veces.”
Sigue este procedimiento:
- Expresa el síntoma visible para una persona o para el sistema sin nombrar una causa.
- Escribe una observación que incluya la preparación de la prueba, la acción y el resultado visible o medido. No incluyas una explicación causal.
- Identifica el supuesto oculto en el reporte original.
- Escribe dos hipótesis alternativas y comprobables. Una puede involucrar daño duplicado; la otra debe ofrecer una explicación distinta. Para cada una, predice evidencia que podría respaldarla o refutarla.
- Describe el mecanismo de cada hipótesis en uno o dos pasos causales. Después, elige una verificación discriminante e indica qué resultado respaldaría cada mecanismo.
- Etiqueta una posible causa raíz. Marca el estado actual de su evidencia como respaldada, refutada o sin verificar e indica qué evidencia haría falta para comprobarla. No la presentes como demostrada salvo que la evidencia disponible la establezca.
Una observación sólida podría comenzar así: “Con el jugador a vida completa y un único contacto con el peligro preparado, el indicador de salud pasó de completo a vacío durante el contacto.” No debería comenzar con “el evento de daño se ejecutó dos veces”, porque eso ya es una explicación.
1405. Validación y evidencia
Completa la evaluación práctica adjunta. Tu entrega debe distinguir el síntoma de la observación delimitada y etiquetar con claridad la observación, el supuesto, dos hipótesis, sus mecanismos, una posible causa raíz, el estado de la evidencia y una verificación discriminante.
Has demostrado la capacidad cuando otra persona del equipo puede determinar:
- qué afirmación describe la manifestación visible;
- qué afirmación está respaldada directamente por las condiciones de la prueba;
- qué afirmaciones siguen sin verificarse;
- cómo produciría el resultado cada mecanismo propuesto;
- por qué la causa raíz solo es posible con la evidencia actual; y
- qué resultado de la verificación cambiaría la siguiente decisión de debugging.
La tarea se limita a la clasificación y al razonamiento causal. La próxima lección desarrolla el reporte más completo de reproducción, acotación y validación.
1406. Ideas clave
- Un síntoma es la manifestación visible de un fallo; una observación registra un síntoma concreto bajo condiciones indicadas y con evidencia directamente disponible.
- Un supuesto es una interpretación que todavía necesita evidencia.
- Una hipótesis útil propone una explicación comprobable y predice evidencia capaz de respaldarla o refutarla.
- Un mecanismo describe la secuencia causal que conecta una condición con el resultado observado.
- Una posible causa raíz debe indicar el estado actual de su evidencia y la evidencia necesaria para verificarla.
- Mantén visibles las explicaciones alternativas hasta que una verificación discriminante las separe.
1407. Próxima lección
Continúa con 3.16 L2 — Reproducir, acotar, validar.
1408. Diagnosticar y recuperar (fix-git-regression)
Abre academy-fixtures/labs/git-regression. Ejecuta node run.mjs. Mapea síntoma → mecanismo → recuperación del estado conocido. Luego aplica el mismo pensamiento si validate.mjs de Pulse Loop se rompe.
1409. Comprobación
Responde estas preguntas por tu cuenta antes de leer las respuestas.
¿Qué afirmación es una observación delimitada y no una explicación?
Mostrar respuesta y explicación
Respuesta: Después de un contacto con un peligro estando a vida completa, el indicador de salud quedó vacío.
Por qué: La afirmación registra una condición y un resultado visible sin explicar por qué ocurrió. Las demás opciones proponen explicaciones o diagnósticos.
¿Qué hace útil a una hipótesis durante el debugging?
Mostrar respuesta y explicación
Respuesta: Propone una explicación comprobable y predice evidencia que podría respaldarla o refutarla.
Por qué: Una hipótesis orienta una verificación porque propone una explicación y predice evidencia observable que podría respaldarla o refutarla.
¿Qué afirmación describe mejor un mecanismo?
Mostrar respuesta y explicación
Respuesta: La recogida actualiza su estado visual, pero el valor de inventario que lee la puerta permanece sin cambios.
Por qué: Un mecanismo describe la secuencia causal que conecta una condición con el resultado observado. Las demás opciones son un síntoma, un supuesto vago o una posible causa raíz.
¿Cuál es la mejor acción siguiente cuando dos mecanismos podrían explicar el mismo síntoma?
Mostrar respuesta y explicación
Respuesta: Diseñar una verificación enfocada cuyos posibles resultados distingan los mecanismos.
Por qué: Una verificación discriminante produce evidencia que respalda un mecanismo, lo refuta o reduce las alternativas sin cambiar sistemas no relacionados.