Explique O Que Aconteceu

Como explicar o que aconteceu em incidentes técnicos

Quando um sistema falha, um bug aparece ou um serviço cai, a primeira reação costuma ser correr para consertar. Só que depois que o fogo se apaga, alguém precisa documentar o evento. Aí é que entra o explique o que aconteceu — não como um ritual burocrático, mas como uma prática que salva reuniões de Blame Game e evita que o mesmo erro volte três meses depois. Eu já vi relatórios de incidente com cinco páginas de logs e nenhuma linha respondendo a pergunta simples: o que mudou e quando. O problema não é falta de informação, é excesso dela. Quem lê o relatório geralmente é um engenheiro ocupado que precisa entender em trinta segundos se aquilo é relevante para o serviço dele. Se você começar jogando timestamps e IDs de trace, já perdeu. A estrutura que funciona é a inversa do que todo mundo faz. Comece pela consequência, não pela causa raiz. Diga primeiro o que quebrou, quanto tempo durou, quantos usuários foram afetados. Só então desça para o mecanismo. Eu tenho um template de uma página que uso desde 2019 e ele sempre começa com três linhas: impacto, duração, estado atual. O resto é detalhe.

O que incluir (e o que pular)

Todo mundo acha que precisa colocar tudo. Não precisa. Um bom explicação tem cinco seções fixas: Eu já perdi tempo corrigindo relatórios onde a causa raiz era "falha humana". Isso não é uma causa, é uma desculpa. A causa real era um fluxo de aprovação que permitia deploy sem review de par. Mude o fluxo, não a pessoa. A primeira armadilha é o efeito pós-mortem. Depois que o incidente vira notícia interna, todo mundo começa a saber o que teria feito diferente. Respeite isso, mas não deixe que o relato final vire um curriculum de heróis. Eu já vi equipes que transformavam incidentes em teatro de bravura, quando na verdade o problema era uma dívida técnica de seis meses que ninguém queria admitir.

A segunda armadilha é o excesso de tecnicismo. Se o relatório for escrito em linguagem que só o autor entende, ele não cumpriu o objetivo. Eu uso uma regra simples: se eu mostrar o relatório para um colega de outra área (produto, suporte, finanças), ele consegue responder a pergunta "quando volta a funcionar?" em dez segundos. Se não conseguir, eu reescrevo. Existe também o viés de confirmação. A gente tende a incluir evidências que apoiam a conclusão que já formou e ignorar as que contradizem. Eu sempre pergunto para um colega não envolvido no incidente: "o que aqui parece inconsistente?" Às vezes a resposta é inconveniente, mas evita que o relatório vire propaganda interna.

Quando explicar o que aconteceu não é suficiente

Em incidentes críticos, o relatório escrito é necessário mas insuficiente. Eu recomendo uma reunião de quinze minutos dentro de quarenta e oito horas, com as pessoas certas, para revisar o documento e adicionar o contexto que ficou de fora. Às vezes o que importa não está nos logs, está na decisão que alguém tomou às três da manhã sem consultar o-time. Se o incidente for recorrente (mais de duas vezes no mesmo trimestre), o relatório individual não resolve. Aí o processo muda: vira uma análise de padrão, não de evento isolado. Eu já vi equipes que gastavam três horas documentando o mesmo bug todo mês, quando o problema real era uma arquitetura que tornava o bug inevitável. Documentar não substitui corrigir a raiz.

Download do template

Eu mantive um template em Markdown no GitHub desde 2020. Ele segue a estrutura de cinco seções que descrevi e inclui exemplos preenchidos de incidentes reais (com dados sensíveis removidos). O link é direto, sem formulário de cadastro: github.com/explique-oque-aconteceu/template. Se você quer adaptar para seu time, comece copiando o template e preenchendo com um incidente recente. A edição é mais fácil quando o contexto já existe. Levanta para testar, pede para um colega fora do time ler, e ajusta até que qualquer pessoa consiga responder as perguntas básicas em dois minutos.