Story Walkthrough (Explicação Narrativa)

O que Story Walkthrough (Explicação Narrativa) faz?

O usuário está pedindo para entender um problema pelo qual ele não passou diretamente. Ele não conhece os componentes, o vocabulário ou a ordem em que as coisas acontecem. Uma lista de descobertas ou um resumo de diff não o ajuda. Uma história sim: ela apresenta cada ator uma vez, depois mostra o que cada um faz, na ordem em que acontece, até que a falha ocorra naturalmente.

Primeiro, investigue. A história só é tão boa quanto os fatos por trás dela, então leia o código, logs, tickets, documentos e o histórico antes de escrever. Se a investigação já aconteceu antes na conversa, reutilize-a em vez de repeti-la.

Formato da resposta

Abra com uma linha que defina o contexto, por exemplo "Aqui está a história completa desde o início, sem presumir que você conhece o código." Em seguida, use estas seções. Pule uma seção que não tenha nada de real a dizer, em vez de enchê-la.

Os personagens

Apresente todos os atores que a história precisa, e nada mais: componentes, classes, mensagens, timers, dados e, para um processo, as pessoas, equipes, formulários e configurações envolvidos. Dê a cada um um nome em negrito e uma ou duas frases simples sobre o que é e o que faz nesta história.

• Nomeie cada personagem com precisão e vincule-o ao código. Escreva price_cache_key() com um link arquivo:linha, não "o construtor de chave". Um rótulo vago faz o leitor parar e perguntar o que significa. Se um personagem abranger várias partes do código (um método mais os hooks do framework ao redor dele), diga isso aqui. Para um problema fora do código, vincule a fonte: o documento e a etapa, o campo do formulário ou o caminho de configuração.
• Escolha uma metáfora física para o mecanismo abstrato e mantenha-a durante toda a história. Por exemplo, cabeçalhos de mensagem se tornam "bilhetes grampeados em um envelope", um cache se torna "um quadro branco", um bloqueio se torna "uma chave". Apresente a metáfora ao lado do nome real ("o cache de preço, um quadro branco ao lado de cada servidor web") para que o leitor possa mapeá-la de volta ao código. Não mude de metáfora no meio do caminho e não acumule duas.
• Dê a regra que cada personagem segue, expressa como o pensamento do próprio personagem em itálico: "Hoje é qualquer data que meu relógio mostrar." Bugs e falhas de processo geralmente vêm de duas regras razoáveis colidindo, e isso torna a colisão visível mais tarde.

Capítulos

Conte o que acontece em ordem cronológica, um capítulo por etapa: ## Capítulo 1: Um comprador olha os preços antes da meia-noite, ## Capítulo 2: Os novos preços chegam e assim por diante. Títulos curtos que digam o que acontece.

• Mantenha cada capítulo curto: algumas frases ou alguns marcadores.
• Coloque em negrito o detalhe chave do capítulo, o único fato que o leitor não pode perder ("a importação apaga o canto errado do quadro branco").
• Quando duas coisas acontecem ao mesmo tempo, dê a isso seu próprio capítulo e mostre os dois lados um após o outro.
• O capítulo da falha cita a mensagem de erro exata como uma citação em bloco e diz qual código a captura e o que registra.

Por que o sintoma parece assim

Após a falha, explique o padrão observado: por que apenas nas primeiras horas, por que apenas em alguns servidores, por que apenas após uma reinicialização. Relacione isso ao que o ticket ou os logs realmente mostraram. Esta é a verificação de que a história está correta, então mantenha-a.

Quando o problema é um risco, não uma falha

Às vezes a história é sobre algo que pode dar errado: um comentário de revisão, um bug latente, um "e se". Nada falhou, então não há linha de log ou sintoma de ticket para ancorar a história. Conte de forma diferente, porque um leitor que vê um erro citado vai presumir que aconteceu.

• Diga logo que não aconteceu. Afirme na linha de abertura ou no primeiro capítulo que esta é uma falha possível encontrada lendo o código, não uma vista em logs ou testes.
• Detalhe as condições. O capítulo da falha lista exatamente o que deve ser verdade para que a falha ocorra, como condições numeradas ("1. a operação chama outro serviço após o escopo fechar e 2. nenhum novo escopo está aberto ao redor dessa chamada"). Em seguida, nomeie o que daria errado: a asserção, o tipo de exceção, a linha. Não cite uma mensagem de erro que ninguém viu. Se você nomear uma exceção, diga que veio da leitura do código.
• Substitua "por que o sintoma parece assim" por "por que nada atinge isso hoje". Percorra cada chamador ou fluxo real e mostre qual condição ele não atende, com links. Esta seção carrega o peso da história, porque o leitor tem que decidir se o risco está ativo.
• Procure pelos chamadores que você não verificou. Escrever a lista de "quão ruim é" para um risco é onde caminhos não verificados aparecem: uma chamada feita fora do lugar usual, um transporte diferente, uma tarefa em segundo plano. Liste cada um como "não verificado" em vez de omiti-lo e diga qual evidência existe (por exemplo, uma execução de teste limpa que o exerceu sem rastreá-lo).
• Compare custos na seção de correção. Uma correção para um risco pode trazer de volta uma falha real. Se isso acontecer, diga claramente: a correção troca um risco que ninguém atinge por uma falha que acontece.

Por que começou agora

Se o comportamento é uma regressão, diga o que mudou, quando e por que essa mudança fazia sentido por si só. Nomeie o PR ou commit em palavras primeiro, com o ID entre parênteses. O leitor precisa saber que a mudança anterior não foi descuidada, apenas incompleta.

Quão ruim é

Liste o impacto real: dados, números, alertas, ruído de log. Separe o que está confirmado do que é inferido, porque o leitor repetirá essas afirmações para outros.

• Marque cada afirmação como verificada (e como: um teste, uma consulta de log, uma leitura de caminho de código de ponta a ponta) ou como não verificada.
• Não escreva "os dados estão bons" a menos que algo tenha verificado. Uma afirmação plausível que se revela errada custa mais confiança do que um honesto "ainda não verificado".

Como corrigir

Dê as opções da menor para a maior (por exemplo, uma correção rápida e uma correção adequada), o que cada uma muda em termos de história ("dar o mesmo calendário a ambos os personagens") e seus limites. Termine com uma recomendação curta.

Estilo

• Palavras simples. Defina cada termo na primeira vez que aparecer, ou deixe-o de fora.
• Mantenha os identificadores de código em backticks ao lado da metáfora, para que a história permaneça rastreável até o código.
• Prefira parágrafos curtos e marcadores a blocos longos.
• Siga as regras de estilo de escrita do usuário do arquivo CLAUDE.md ou AGENTS.md.

Após a história

Espere perguntas de acompanhamento sobre um personagem ("Então X é o manipulador?"). Responda fixando o personagem no código exato: liste o que é executado, em ordem, com links arquivo:linha, e diga qual parte faz a coisa que importa. Se a pergunta mostrar que a história original nomeou algo de forma vaga, corrija a nomeação na sua resposta em vez de defendê-la.

Exemplo

references/example-stale-prices.md contém uma história completa escrita neste estilo para um bug de cache obsoleto, além de notas sobre o que errou. Leia-o antes de escrever sua primeira história em uma sessão, para calibrar o comprimento e o tom.