# Depuración y análisis de causa raíz Va del fallo observado a la causa que lo produce — y demuestra la causa haciendo que el defecto aparezca y desaparezca a voluntad. ## Entregable Un documento Markdown, `root-cause-report.md`, con la estructura fijada en **Salida** más abajo. Su arreglo alimenta **Planificación de implementación** cuando el cambio es lo bastante grande como para necesitar uno. ## Entradas obligatorias - **El reporte del defecto** — qué se observó, dónde, cuándo y quién lo vio. Una expectativa y una observación, no solo la sensación de que algo va mal. - **Acceso a la evidencia** — registros, el código, una reproducción, o el sistema en el estado que muestra el fallo. Hace falta al menos uno de ellos. Si falta cualquiera de las dos, detente y repórtalo. Una causa propuesta sin evidencia es una conjetura con un párrafo de razonamiento pegado. ## Entradas opcionales - Una reproducción fiable, y el entorno en el que se ejecuta - El historial de cambios del área, y qué se publicó antes de que apareciera el fallo - Salida de monitorización, trazas y tasas de error alrededor del suceso - La configuración y los datos contra los que se ejecutó el sistema - Reportes del mismo síntoma en otros momentos o lugares - El conjunto de pruebas, y si pasa en la revisión que falla Las entradas opcionales ausentes reducen lo que se puede demostrar, no lo que se puede afirmar. Cada conclusión declara la evidencia en la que se apoya, y la que no se apoya en ninguna se escribe como hipótesis. ## Ejecución **1 — Separar el síntoma del relato.** Registra qué se observó y qué se esperaba, en palabras de quien lo vio, con la hora, el entorno y las entradas en juego. Quita la explicación que ya venía pegada al reporte: una teoría temprana estrecha la búsqueda antes de empezarla. **2 — Conseguir una reproducción fiable.** Haz que el defecto aparezca a voluntad, y registra los pasos, entradas y estado exactos que lo consiguen. Si no se puede reproducir, dilo y continúa solo desde la evidencia — pero marca como no probada cada conclusión posterior, porque no hay nada que comprobar. **3 — Fijar el límite.** Establece qué sí funciona: la última revisión buena conocida, las entradas que pasan, el entorno donde el fallo no aparece. La causa está entre lo que funciona y lo que no, y esa es la única región que vale la pena buscar. **4 — Estrechar por mitades.** Bisecciona el historial de revisiones, la entrada, los datos o el camino de llamadas — la dimensión que separe lo que funciona de lo que falla. Registra cada división y su resultado. La bisección converge; leer código esperando notar algo, no. **5 — Separar la causa próxima de la condición que la permitió.** La línea que falló rara vez es toda la respuesta. Registra ambas: qué se rompió, y qué dejó existir el estado roto — la validación que falta, el camino sin tratar, la suposición que nunca se comprobó. **6 — Demostrarlo.** Haz que el defecto aparezca y desaparezca a voluntad introduciendo y retirando la causa. Una causa que no se puede encender y apagar es una hipótesis, y se escribe en el informe como tal, con el experimento que la resolvería. **7 — Buscar la misma causa en otros sitios.** Busca en el código el patrón que la produjo. Una causa encontrada una vez y arreglada una vez suele seguir existiendo en los sitios a los que se copió. ## Salida `root-cause-report.md`, en este orden: - **1. Síntoma** — qué se observó, qué se esperaba, dónde, cuándo, y quién lo reportó - **2. Reproducción** — los pasos y el estado exactos que lo producen, o la declaración de que no se pudo reproducir - **3. Cadena de evidencia** — cada división hecha, qué mostró, y qué descartó - **4. Causa próxima** — el punto de fallo, con archivo y línea - **5. Condición subyacente** — qué permitió que existiera el estado que falla - **6. Demostración** — cómo se encendió y se apagó el defecto, o el experimento que aún hace falta - **7. Arreglo** — el cambio que elimina la causa, y lo que no cubre - **8. La prueba que lo habría detectado** — qué comprueba y dónde va - **9. La misma causa en otros sitios** — los demás lugares donde aparece el patrón, con sus rutas - **10. Sin resolver** — hipótesis no zanjadas, y qué zanjaría cada una ## Validación El informe está listo cuando se cumple todo esto: - La sección 2 da una reproducción o declara con claridad que no la hay - Cada paso de la sección 3 registra qué descartó, no solo qué miró - La sección 4 nombra un archivo y una línea, o declara que el punto de fallo no se localizó - La sección 6 muestra el defecto apareciendo y desapareciendo, o la sección 10 carga con la hipótesis - La sección 8 nombra una prueba que falla antes del arreglo y pasa después - Ninguna afirmación del informe se apoya en evidencia que no se aportó Falla la ejecución si se declara probada una causa sin la demostración de la sección 6, o si el arreglo ataca el síntoma mientras sigue en pie la condición de la sección 5. ## Gestión de fallos - **No se puede reproducir** — entrega el informe con la sección 2 declarándolo, trabaja solo desde los registros y el código, y marca cada conclusión como hipótesis con su experimento resolutorio en la sección 10. - **Sin registros y sin acceso** — detente. Informa de que no hay nada que analizar, y nombra la evidencia necesaria. - **Varias causas plausibles** — lístalas todas en la sección 10 con el experimento que las distingue, y no arregles ninguna hasta probar una. Arreglar dos cosas a la vez destruye la evidencia. - **El defecto deja de ocurrir solo** — regístralo como sin resolver con las condiciones en las que apareció, y añade la monitorización que detectaría su vuelta. Un fallo inexplicado que se fue es un fallo esperando carga. - **El arreglo queda fuera de alcance** — reporta la causa, la contención disponible ahora, y lo que necesita el arreglo real. La contención se registra como contención, nunca como resolución.