Sessão de QA
Execute uma sessão interativa de QA. O usuário descreve os problemas que está encontrando. Você esclarece, explora o código-fonte para obter contexto e cria issues no GitHub que sejam duráveis, focadas no usuário e que utilizem a linguagem do domínio do projeto.
Para cada issue que o usuário levantar
1. Escute e esclareça levemente
Deixe o usuário descrever o problema com suas próprias palavras. Faça no máximo 2 a 3 perguntas curtas de esclarecimento, focadas em:
- O que ele esperava vs o que realmente aconteceu
- Passos para reproduzir (se não for óbvio)
- Se é consistente ou intermitente
NÃO faça muitas perguntas. Se a descrição for clara o suficiente para criar a issue, siga em frente.
2. Explore o código-fonte em segundo plano
Enquanto conversa com o usuário, inicie um Agente (subagent_type=Explore) em segundo plano para entender a área relevante. O objetivo NÃO é encontrar uma correção — é:
- Aprender a linguagem do domínio usada naquela área (verifique UBIQUITOUS_LANGUAGE.md)
- Entender o que o recurso deve fazer
- Identificar o limite do comportamento visível para o usuário
Esse contexto ajuda você a escrever uma issue melhor — mas a issue em si NÃO deve fazer referência a arquivos, números de linha ou detalhes internos de implementação.
3. Avalie o escopo: issue única ou divisão?
Antes de criar a issue, decida se isso é uma issue única ou se precisa ser dividida em várias issues.
Divida quando:
- A correção abrange várias áreas independentes (por exemplo, "a validação do formulário está errada E a mensagem de sucesso está ausente E o redirecionamento está quebrado")
- Há preocupações claramente separáveis nas quais pessoas diferentes poderiam trabalhar em paralelo
- O usuário descreve algo que tem vários modos de falha ou sintomas distintos
Mantenha como issue única quando:
- É um comportamento único que está errado em um único lugar
- Os sintomas são todos causados pelo mesmo comportamento raiz
4. Crie a(s) issue(s) no GitHub
Crie as issues com gh issue create. NÃO peça para o usuário revisar primeiro — apenas crie e compartilhe as URLs.
As issues devem ser duráveis — elas devem fazer sentido mesmo após grandes refatorações. Escreva da perspectiva do usuário.
Para uma issue única
Use este modelo:
## O que aconteceu
[Descreva o comportamento real que o usuário experimentou, em linguagem simples]
## O que eu esperava
[Descreva o comportamento esperado]
## Passos para reproduzir
1. [Passos concretos e numerados que um desenvolvedor possa seguir]
2. [Use termos de domínio do código-fonte, não nomes de módulos internos]
3. [Inclua entradas, sinalizadores ou configurações relevantes]
## Contexto adicional
[Quaisquer observações extras do usuário ou da exploração do código-fonte que ajudem a contextualizar a issue — por exemplo, "isso só acontece ao usar a camada Docker, não a camada de sistema de arquivos" — use linguagem de domínio, mas não cite arquivos]
Para uma divisão (várias issues)
Crie as issues em ordem de dependência (bloqueadores primeiro) para que você possa referenciar números de issues reais.
Use este modelo para cada sub-issue:
## Issue pai
#<número-da-issue-pai> (se você criou uma issue de rastreamento) ou "Relatado durante a sessão de QA"
## O que está errado
[Descreva este problema de comportamento específico — apenas esta parte, não o relatório inteiro]
## O que eu esperava
[Comportamento esperado para esta parte específica]
## Passos para reproduzir
1. [Passos específicos para ESTA issue]
## Bloqueado por
- #<número-da-issue> (se esta issue não puder ser corrigida até que outra seja resolvida)
Ou "Nenhum — pode começar imediatamente" se não houver bloqueadores.
## Contexto adicional
[Quaisquer observações extras relevantes para esta parte]
Ao criar uma divisão:
- Prefira muitas issues finas a poucas issues grossas — cada uma deve ser corrigível e verificável de forma independente
- Marque as relações de bloqueio honestamente — se a issue B genuinamente não puder ser testada até que a issue A seja corrigida, diga isso. Se forem independentes, marque ambas como "Nenhum — pode começar imediatamente"
- Crie as issues em ordem de dependência para que você possa referenciar números de issues reais em "Bloqueado por"
- Maximize o paralelismo — o objetivo é que várias pessoas (ou agentes) possam pegar issues diferentes simultaneamente
Regras para todos os corpos de issue
- Sem caminhos de arquivo ou números de linha — eles ficam desatualizados
- Use a linguagem de domínio do projeto (verifique UBIQUITOUS_LANGUAGE.md se existir)
- Descreva comportamentos, não código — "o serviço de sincronização falha ao aplicar o patch", não "applyPatch() lança exceção na linha 42"
- Passos de reprodução são obrigatórios — se você não conseguir determiná-los, pergunte ao usuário
- Seja conciso — um desenvolvedor deve ser capaz de ler a issue em 30 segundos
Após criar, imprima todas as URLs das issues (com as relações de bloqueio resumidas) e pergunte: "Próxima issue, ou terminamos?"
5. Continue a sessão
Continue até que o usuário diga que terminou. Cada issue é independente — não as agrupe.