Debrief

O que Debrief faz?

Um debrief é o instrumento de uma meta-meta permanente: um processo que melhora nossos processos. Ele examina como a pessoa e o agente trabalharam juntos, com evidências, e transforma o que encontra em três tipos de resultado: lições para o agente (instruções, skills, workflows, hooks), lições para a pessoa (como liderar melhor o agente) e mudanças na configuração do projeto. Ele é honesto em ambas as direções e nunca fabrica críticas: uma sessão que correu bem recebe um relatório curto.

Estrutura e regras adaptadas de dois skills licenciados sob MIT, com agradecimentos: debrief por Wavez (os quatro grupos de verificação, "cada descoberta cita um momento", nada aplicado sem aprovação) e retrospective por florianbuetow (relatórios mantidos como histórico, recomendações anteriores verificadas e problemas recorrentes escalados, causa raiz e sugestão por descoberta). A seção de coaching, o hábito dos cinco porquês e o script de uso são próprios deste skill.

Entradas

1. A conversa. A fonte primária: chamadas de ferramenta, perguntas e quando foram feitas, correções e confirmações pelo usuário, relatórios de subagentes, erros e repetições. Se a sessão foi compactada, diga isso no relatório e trate o resumo como evidência de baixa confiança; não invente momentos para a parte que você não pode ver.

2. Os números. Execute o script incluído para o uso da sessão: turnos, chamadas de ferramenta por nome, subagentes e workflows com seus tokens, modelos usados, tokens de saída por modelo, duração, compactações. Ele lê a transcrição da sessão em ~/.claude/projects/<project-slug>/ e o diretório subagents/ ao lado. O usuário pode perguntar sobre outra sessão; então passe seu ID.

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py            # a sessão atual (transcrição mais recente deste projeto)
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py <session-id>
   

3. O registro do projeto. Os arquivos de instrução (CLAUDE.md, AGENTS.md), o backlog e o log de decisões se o projeto os mantiver, e as memórias de feedback do agente para este projeto (~/.claude/projects/<project-slug>/memory/), para que um erro repetido seja reconhecido como repetição.

4. Debriefs anteriores. Os últimos três relatórios no diretório de relatórios (abaixo). Para cada recomendação que fizeram, anote se foi atendida, se é recorrente ou se é desconhecida; um problema recorrente tem sua severidade escalada.

Combine o esforço com a extensão: uma sessão curta e limpa recebe uma passagem rápida; uma sessão de várias semanas recebe o tratamento completo e os cinco porquês nos padrões maiores.

O que examinar

Percorra estes quatro grupos. Para cada descoberta, cite o momento (o que foi dito ou feito, aproximadamente quando), diga por que foi importante, e pergunte "por quê" além da instância até chegar a uma causa de processo ou um princípio, ou até que a resposta saia do controle do projeto. Mantenha observações e prescrições separadas: uma observação pode estar correta enquanto a correção proposta está errada.

1. Eficiência. Chamadas de ferramenta redundantes ou repetidas, lógica escrita manualmente que um script ou skill deveria ter carregado, ciclos extras de construção ou teste, trabalho que poderia ter sido agrupado, subagentes que foram ignorados ou que valeram a pena, retrabalho após compactação, trabalho em segundo plano que morreu com a sessão.
2. Colaboração. Perguntas feitas cedo demais, tarde demais ou não feitas; instruções permanentes não seguidas; exemplos interpretados literalmente onde uma regra era pretendida; verborragia; se o agente disse qual interpretação de uma solicitação ambígua escolheu; se perguntas bloqueadoras realmente bloquearam.
3. Correção e disciplina. Alegações feitas sem evidência; restrições descobertas tarde; ações destrutivas ou irreversíveis sem confirmação; convenções do projeto ignoradas; as perguntas "qual cenário pede isso" e "o que teria pego isso" ignoradas.
4. Levar adiante. Preferências e decisões que valem a pena salvar como memória ou documentos do projeto; propostas que são um skill, um workflow, um hook, uma regra permanente ou um item do backlog; ferramentas que teriam facilitado a extensão; passos que poderiam ser automatizados na próxima vez. Duas repetições escritas à mão sinalizam um ativo reutilizável faltando.

Depois, as duas partes que tornam este skill pessoal:

• Coaching para a pessoa. Como a pessoa que escreve os prompts poderia ter sido mais eficaz? Quais de suas ações ajudaram mais (nomeie-as, para que sejam repetidas) e quais custaram (escopo vago, um rótulo faltando em um exemplo, uma decisão retida que o agente precisava, uma revisão ignorada)? Escreva diretamente para a pessoa, como um colega em um grupo de supervisão faria: específico, baseado em evidências, sem bajulação e sem suavização.
• Modelos e esforço. A partir dos números: o modelo e o nível de esforço foram proporcionais ao trabalho? Para onde foram os tokens (loop principal, subagentes, workflows), e um modelo mais barato ou um esforço menor teriam sido suficientes para partes disso? Onde um esforço alto valeu a pena?

Relatório

Escreva o relatório no diretório de relatórios e mostre um resumo curto na resposta. O diretório é docs/debriefs/ no repositório atual quando o repositório tem um diretório docs/, caso contrário ~/.claude/debriefs/<project-slug>/; o usuário pode nomear outro. Nome do arquivo AAAA-MM-DD.md, com um sufixo -2 se um existir.

Curto e denso: o leitor é a pessoa que viveu a sessão, então o relatório lembra ao invés de narrar. A nuance vive na evidência e na causa, não na prosa ao redor delas. Use este modelo:

# Debrief <data>: <sobre o que foi o período>

Cobertura: <o que o debrief pôde ver; compactação anotada>. Debriefs anteriores: <datas ou nenhum>.

## Em cinco linhas
- <o que o período alcançou>
- <o que o fez funcionar>
- <o que custou>
- <o coaching em uma linha>
- <quantas propostas, e a que não é pequena>

## Números
<um parágrafo do script: duração, turnos, chamadas de ferramenta com as principais, tokens de saída por modelo, subagentes, compactações>

## O que correu bem
- **<rótulo de duas palavras>.** <o momento> → <o que proporcionou>.

## O que custou
- 🔴 / 🟡 / 🟢 **<rótulo>.** <o momento, uma linha>.
  Causa: <a causa do processo depois de perguntar por quê>. <Corrigido, ou o que resta>.

## Coaching para <a pessoa>
Continue fazendo: <as ações que ajudaram, como uma lista em uma linha>.
1. **<hábito>.** <evidência> e <o que fazer em vez disso>, uma ou duas frases.

## Modelos e esforço
<um parágrafo: proporcional ou não, e os números que o dizem>

## Propostas
| # | Proposta | Destino | Esforço | Decisão |
|---|---|---|---|---|
Destinos: regra do AGENTS.md ou CLAUDE.md, memória, skill, workflow, hook, backlog, o guia compartilhado, uma ferramenta para adotar.

## Recomendações anteriores
| De | Recomendação | Status (atendida / recorrente / desconhecida) |

Severidade: 🔴 custou trabalho real ou correu risco de dano; 🟡 custou tempo ou atenção; 🟢 um pequeno hábito.

Regras

• Apenas um relatório. Nada é escrito em arquivos de instrução, memória ou backlog até que o usuário aprove uma proposta; então aplique exatamente aquela.
• Cada descoberta cita um momento. Se você não puder apontar um, descarte a descoberta.
• Não inflacione: três descobertas reais valem mais que dez infladas, e "este período correu bem" é um resultado válido.
• O coaching é para o benefício da pessoa, portanto deve ser sincero; também é privado por padrão, então mantenha-o fora de qualquer coisa que a pessoa não pediu para compartilhar.
• Linguagem simples e acionável: escreva cada item de modo que uma pessoa ou agente que não estava na sessão possa agir sobre ele. Nomeie uma prática como um comportamento (o que alguém faz e o que alcança: "especifique o resultado, não a solução"), nunca por um apelido que a sessão cunhou ("a solução retida", "céticos", "a olho"); se a abreviação ajudar no reconhecimento, coloque-a após a forma completa entre parênteses. O teste: um colega poderia copiar a linha para seu próprio guia e segui-la?
• Brevidade: um rótulo em negrito, depois uma linha de evidência, depois a causa. Se uma descoberta precisar de um parágrafo, são duas descobertas ou ainda não foi compreendida. Mire em uma tela por seção.
• Lições versus atrito: uma lição é algo que você contaria a outro agente em outro projeto; o que se aplica apenas a esta sessão é atrito e vai para as descobertas, não para propostas de regras permanentes.