Cuando la IA participa en un pull request que provoca un fallo, el postmortem no debería terminar en “lo escribió el modelo”. Esa frase identifica una circunstancia, pero no explica qué requisito quedó ambiguo, qué revisión no detectó el riesgo, qué prueba faltaba o qué señal llegó demasiado tarde.

Un postmortem útil reconstruye cuatro cosas: el cambio que llegó al repositorio, el contexto de revisión y entrega, el impacto en runtime y el control que va a cambiar. Cada afirmación tiene una evidencia o una etiqueta explícita: observado, inferido, hipotético o desconocido. Cada acción tiene responsable, prueba de aceptación y fecha. Esto complementa el registro de decisiones de ingeniería cuando un agente escribe código, que cubre decisiones tomadas antes o durante la implementación.

Diagrama que conecta el cambio, la revisión y el impacto en runtime con una acción de control en un postmortem de código asistido por IA.

Respuesta corta

  • Reconstruye el cambio a partir del commit, el pull request y la traza del agente cuando exista.
  • Separa revisión, CI, aprobación y despliegue de la explicación de lo ocurrido en runtime.
  • Etiqueta cada afirmación como observed, inferred, hypothesized o unknown.
  • Cambia “revisar mejor” por un control verificable, con responsable y criterio de aceptación.

¿Qué debe responder el postmortem?

Empieza con una frase de impacto que alguien fuera del incidente pueda verificar: qué cambió, qué comportamiento se observó, a quién afectó y cómo terminó la recuperación. No empieces atribuyendo una intención al modelo ni a la persona autora.

Después responde estas preguntas, en orden:

  1. ¿Qué requisito, decisión o supuesto debía satisfacer el cambio?
  2. ¿Qué se produjo y qué herramientas participaron?
  3. ¿Qué comprobaron realmente la revisión humana, la automatización y la aprobación?
  4. ¿Cuál fue la primera señal observable en producción o durante la entrega?
  5. ¿Qué control faltaba, era débil o se aplicó demasiado tarde?
  6. ¿Cómo sabremos que la acción correctiva funciona?

Esto sigue un análisis sin búsqueda de culpables. La guía de Google SRE sobre la cultura de postmortems recomienda identificar causas contribuyentes sin acusar a una persona o equipo. La guía de GitHub para revisar código generado por IA también coloca la experiencia humana, las pruebas, el análisis estático y la comprobación del contexto junto a la automatización.

Construye tres líneas de evidencia

Un cambio asistido por IA deja evidencias en lugares distintos. No mezcles todos los eventos en una sola historia antes de decidir qué puede demostrar cada fuente.

Línea Pregunta Evidencias posibles Límite
Cambio ¿Qué entró en el repositorio y de dónde salió? commit, diff, pull request, instrucción, archivos modificados, traza del agente Una traza puede mostrar una llamada sin demostrar que causó el defecto.
Revisión y entrega ¿Qué se revisó, probó y aprobó? comentarios, checks, artefactos de CI, aprobación, despliegue, configuración Un check verde demuestra lo que ejecutó, no todo lo que el sistema necesitaba.
Runtime ¿Qué ocurrió después de la entrega? log redactado, métrica, alerta, ticket, rollback, consulta de estado Un horario cercano no demuestra causalidad por sí solo.

Si tu harness registra trazas, úsalas para conectar generaciones, llamadas de herramientas, handoffs y guardrails. La documentación de tracing del Agents SDK documenta traces y spans para estos eventos y advierte que los datos capturados pueden ser sensibles. Guarda referencias, hashes o extractos redactados en el postmortem. No copies prompts, tokens, secretos o una transcripción completa solo porque existe.

Para cada fuente, registra su identificador y la afirmación que permite sostener. ci-184 puede demostrar que una suite se ejecutó contra un commit concreto. No demuestra que se consideró una regla de negocio que no estaba representada.

Separa hecho, inferencia, hipótesis y desconocido

Usa etiquetas explícitas para que una hipótesis cómoda no se convierta en la causa oficial durante la edición del documento.

Etiqueta Significado Ejemplo
observed Hay evidencia directa y referenciada. “La alerta checkout-error-rate se abrió a las 14:07.”
inferred La conclusión combina evidencias, pero no se observa directamente. “El cambio probablemente afectó checkout porque el error siguió al despliegue y apareció solo en ese camino.”
hypothesized Es una explicación plausible que aún necesita una prueba suficiente. “La ausencia del caso de moneda puede haber dejado incompleta la validación.”
unknown Falta la fuente necesaria, está demasiado redactada o no permite concluir. “No sabemos qué instrucción recibió el agente en este intento.”

Una marca de tiempo de CI, un comentario de revisión y un log de producción pueden formar una línea temporal coherente. Aun así, distingue “ocurrió después” de “lo causó”. Si la causa sigue como hypothesized, una acción puede ser una prueba que la confirme o descarte.

Convierte la línea temporal en una matriz

Una tabla breve suele ser más fácil de auditar que varios párrafos. Usa IDs estables para que una afirmación pueda apuntar a más de una fuente.

14:02  C1  commit 8f2a abrió el PR                [observed]
14:05  R1  dos checks de CI terminaron en verde   [observed]
14:09  D1  terminó el despliegue de 8f2a          [observed]
14:17  P1  aumentaron los errores de checkout      [observed]
14:31  A1  terminó el rollback a 7c1d              [observed]

Después escribe una matriz de afirmaciones:

ID Afirmación Estado Evidencia Próximo paso
C1 El pull request cambió la normalización de moneda. observed diff 8f2a Ninguno, hecho establecido.
C2 El caso de moneda ausente no tenía una prueba. inferred suite ci-184, cobertura del módulo Añadir una prueba de aceptación.
C3 El agente recibió una instrucción ambigua. unknown traza redactada sin el prompt Mejorar la retención segura o no afirmarlo.

Esta matriz permite que una persona cuestione una afirmación sin reabrir toda la narrativa. El handbook de postmortems de Atlassian ofrece una combinación práctica parecida de línea temporal, causas, responsables y acciones. Úsalo como guía de proceso, no como prueba de que todo incidente necesita un formulario fijo.

Valida el documento antes de publicarlo

El formato puede tener una comprobación pequeña y determinista. La fixture siguiente no analiza el código del agente ni demuestra una causa de producción. Solo impone dos invariantes del documento: una afirmación observada apunta a una evidencia y cada acción tiene responsable y criterio de aceptación.

import assert from "node:assert/strict";

const report = {
  claims: [
    {
      id: "C1",
      status: "observed",
      evidence: ["diff-8f2a", "ci-184"],
    },
    {
      id: "C2",
      status: "hypothesized",
      evidence: [],
    },
  ],
  actions: [
    {
      id: "A1",
      control: "Add the missing currency case to the merge test",
      owner: "checkout-team",
      acceptance: "ci-201 fails before the fix and passes after it",
      due: "2026-12-01",
    },
  ],
};

function validatePostmortem(value) {
  assert.ok(value.claims.length > 0, "postmortem needs claims");

  for (const claim of value.claims) {
    if (claim.status === "observed") {
      assert.ok(claim.evidence.length > 0, `${claim.id} needs evidence`);
    }
  }

  for (const action of value.actions) {
    assert.ok(action.owner, `${action.id} needs an owner`);
    assert.ok(action.acceptance, `${action.id} needs acceptance criteria`);
    assert.ok(action.due, `${action.id} needs a due date`);
  }
}

validatePostmortem(report);
console.log("postmortem evidence checks passed");

Guárdala como postmortem-check.mjs y ejecútala con node postmortem-check.mjs. En un sistema real, conecta la validación con el repositorio del postmortem o con el proceso de revisión. No hagas que el script finja que una acción está completa solo porque sus campos existen.

Convierte la causa en un control

Una acción correctiva debe cambiar el sistema que permitió el fallo. Por ejemplo:

Control perdido Acción verificable
El requisito tenía un hueco Añadir un caso de aceptación que falle con el comportamiento anterior y pase con el nuevo.
La revisión no tenía contexto operativo Adjuntar al PR un resumen redactado del cambio, el riesgo y los checks ejecutados.
La CI no cubría una frontera Crear una prueba de regresión y hacerla obligatoria para el camino afectado.
Los permisos eran demasiado amplios Restringir la herramienta o el entorno y verificar la política en CI.
La primera señal llegó tarde Añadir una alerta con umbral, responsable y prueba de disparo.

“Revisar con más atención” no tiene criterio de finalización. El artículo sobre observabilidad de agentes de código ayuda a conectar el rastro operativo con el PR, y la prueba de aprobación humana para agentes de IA trata una barrera humana como comportamiento comprobable.

¿Qué no debe entrar en el documento?

No publiques una transcripción completa del agente, secretos, prompts privados, tokens, datos personales ni una historia que atribuya intención sin evidencia. Tampoco conviertas una discusión de comunidad en una prueba técnica. Conserva lo que permite aprender y elimina lo que aumenta la exposición sin mejorar la explicación.

No afirmes que la IA fue la causa solo porque participó en el cambio. Compara la especificación, el diff, los checks y el comportamiento observado. Si la contribución del agente no se puede reconstruir de forma segura, márcala como unknown y convierte la observabilidad segura en una acción separada.

Método y límites

Samuel Fajreldines escribió este artículo como una síntesis de documentación pública de SRE, revisión de código generado por IA, tracing de agentes y prácticas de postmortem, combinada con la fixture local anterior. La fixture se ejecutó con Node.js, pero no representa un incidente de producción, no es un benchmark y no mide la eficacia de un modelo. La asistencia de IA ayudó a organizar la investigación y la redacción; no ejecutó una prueba de producción ni sustituyó la responsabilidad del autor. La herramienta del autor es RemoteCode.

Adapta el resultado a tus controles de acceso, retención de logs y requisitos de privacidad. Si una traza del agente contiene datos sensibles, omitir una copia del postmortem puede ser la decisión correcta, siempre que exista una referencia segura y auditable.

Checklist final

  • [ ] La línea temporal apunta a commits, checks, despliegues y señales observables.
  • [ ] Cambio, revisión y runtime están en líneas separadas.
  • [ ] Cada afirmación está etiquetada como observada, inferida, hipotética o desconocida.
  • [ ] La acción cambia un control y tiene responsable, prueba de aceptación y fecha.
  • [ ] El documento no expone secretos, datos personales ni una transcripción innecesaria.
  • [ ] La causa es proporcional a lo que permiten afirmar las evidencias.