O que Sessão de QA faz?
Execute uma sessão interativa de QA. O usuário descreve problemas que está encontrando. Você esclarece, explora o codebase em busca de contexto e abre issues no GitHub que sejam duráveis, focadas no usuário e que usem a linguagem de domínio do projeto.
Para cada issue que o usuário levantar
1. Ouça e esclareça levemente
Deixe o usuário descrever o problema em suas próprias palavras. Faça no máximo 2-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 uma entrevista excessiva. Se a descrição for clara o suficiente para registrar uma issue, prossiga.
2. Explore o codebase 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 de domínio usada naquela área (verifique UBIQUITOUS_LANGUAGE.md)
- Entender o que a funcionalidade deveria fazer
- Identificar o limite do comportamento voltado ao usuário
Este contexto ajuda você a escrever uma issue melhor — mas a issue em si NÃO deve referenciar arquivos, números de linha ou detalhes de implementação internos específicos.
3. Avalie o escopo: issue única ou divisão?
Antes de registrar, decida se isso é uma issue única ou precisa ser dividida em várias issues.
Divida quando:
- A correção abrange várias áreas independentes (ex.: "a validação do formulário está errada E a mensagem de sucesso está faltando E o redirecionamento está quebrado")
- Existem preocupações claramente separáveis nas quais diferentes pessoas poderiam trabalhar em paralelo
- O usuário descreve algo que tem múltiplos modos de falha ou sintomas distintos
Mantenha como uma issue única quando:
- É um comportamento errado em um único lugar
- Os sintomas são todos causados pelo mesmo comportamento raiz
4. Registre a(s) issue(s) no GitHub
Crie issues com gh issue create. NÃO peça para o usuário revisar primeiro — apenas registre e compartilhe as URLs.
As issues devem ser duráveis — elas ainda devem fazer sentido 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 codebase, não nomes de módulos internos]
3. [Inclua entradas, flags ou configurações relevantes]
## Contexto adicional
[Quaisquer observações extras do usuário ou da exploração do codebase que ajudem a contextualizar a issue — ex.: "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 issues em ordem de dependência (bloqueadores primeiro) para que você possa referenciar números de issue 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 independentemente corrigível e verificável
- Marque 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 issues em ordem de dependência para que você possa referenciar números de issue 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 — estes ficam obsoletos
- 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 para reproduzir são obrigatórios — se você não conseguir determiná-los, pergunte ao usuário
- Mantenha conciso — um desenvolvedor deve ser capaz de ler a issue em 30 segundos
Após registrar, 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.