Refinar História de Usuário

O que Refinar História de Usuário faz?

Refinar uma História de Usuário por meio de exame socrático: entrevistar o PO em rodadas estruturadas até que a fronteira de decisão esteja vazia, então sintetizar. Uma sessão eficaz transforma uma discussão de refinamento de 40 minutos em uma confirmação de 10 minutos, porque a equipe chega ao planejamento com decisões registradas e lacunas explicitamente identificadas.

A história pertence ao PO. Você audita, propõe e pergunta; cada edição preserva o objetivo de negócio original, e qualquer reescrita que exigiria decisões de escopo se torna uma pergunta, não uma escolha unilateral. O risco de invenção é agudo aqui: uma HU existente frequentemente parece "quase pronta" e a tentação de completá-la silenciosamente é forte. Uma HU com lacunas visíveis é muito mais valiosa para refinamento do que uma história "completa" com regras que o PO nunca escreveu.

HU: $ARGUMENTS

Antes de começar

Leia docs/agents/refinement.md no workspace: ele define o modo operacional (com ou sem código), o idioma (en-US ou pt-BR, padrão en-US), os slugs e os caminhos de publicação. Se faltar, peça ao usuário para executar /configure-refinement e pare. Todo diálogo de exame, perguntas e o artefato sintetizado seguem o idioma configurado do workspace.

Passos

1. Carregar. Leia a HU (caminho do arquivo, ID do rastreador ou texto colado), CONTEXT.md, ADRs de domínio e invoque a ferramenta Skill para requirements-rigor. Se .scratch/<slug>/ já existir para esta HU, inspecione seu conteúdo: uma sessão anterior pode ter resolvido perguntas, as quais você não deve repetir. O slug segue as convenções em docs/agents/refinement.md. Se docs/adr/ ou .scratch/ estiverem ausentes, prossiga sem aviso. Concluído quando: você pode classificar a HU em uma única linha: ANALISÁVEL (tem narrativa e alguns critérios, mesmo que falhos), ESQUELETO (apenas título, ou narrativa sem critérios) ou NÃO É UMA HU (épico disfarçado, tarefa técnica, requisito não funcional independente).

2. Triagem. NÃO É UMA HU: informe que tipo de artefato é realmente, forneça uma justificativa de 2 a 3 linhas e recomende o tratamento adequado: épico disfarçado, decomponha com /requirements-discovery; tarefa técnica, reclassifique como tarefa; requisito não funcional independente, mova para lista de requisitos não funcionais. Se o item estiver no workspace, adicione Status: not a US (ou Status: não é US) e a justificativa abaixo do título para deixar um rastro. Pare aqui. ESQUELETO: prossiga, e a primeira rodada de exame pede os cenários faltantes em vez de inventá-los. Concluído quando: a classificação é declarada em uma única linha e, no caso de NÃO É UMA HU, a justificativa e o tratamento também são fornecidos.

3. Auditar silenciosamente. Aplique as regras de requirements-rigor à narrativa e aos critérios: INVEST, Gherkin, anti-padrões (leia ANTI-PATTERNS.md separadamente), termos que sempre disparam perguntas. Cada descoberta se torna uma pergunta candidata ou uma correção que preserva o comportamento exato descrito: converter prosa em Gherkin, mover DoD para fora dos critérios, mover tarefas de implementação para notas. Concluído quando: cada critério tem um destino (manter, converter, mover, perguntar) e cada termo ambíguo tem uma pergunta candidata.

4. Buscar fatos antes de perguntar. Fatos são sua responsabilidade, nunca do PO. Para cada pergunta candidata, busque fontes no workspace: glossário, histórias anteriores em .scratch/, documentos anexados pelo PO. No modo com código, despache um subagente para pesquisar a base de código pelo que a HU afirma ou assume: a regra existe? o limite está implementado? a função de integração funciona? Um fato encontrado se torna uma resposta recomendada citando a fonte. No modo sem código, a busca é restrita a arquivos do workspace sem subagentes; se nada for encontrado, declare isso em uma única linha no topo da rodada 1. Concluído quando: cada pergunta candidata está marcada como respondida por uma fonte (com citação) ou em aberto para o PO.

5. Examinar. Invoque a ferramenta Skill para socratic-examination e siga sua disciplina: rodadas, fronteira, respostas recomendadas com citações ou "sem recomendação", fatos seus e decisões do PO, glossário atualizado imediatamente. A Rodada 1 abre com triagem de uma linha, marca perguntas que bloqueiam o veredito e fecha com notas sobre critérios movidos sem perguntas e perguntas encaminhadas para a equipe de engenharia. Perguntas arquiteturais não entram em rodadas com o PO: encaminhe-as diretamente para perguntas abertas da equipe de engenharia. Perguntas que o PO não pode responder recebem [TO CONFIRM: quem] (ou [A CONFIRMAR: quem]) e saem da fronteira. Concluído quando: a fronteira está vazia, ou o PO solicita fechar com as informações atuais.

6. Sintetizar. Escreva a HU refinada seguindo TEMPLATE.md, com as lacunas restantes visíveis como marcadores. Execute a autoauditoria Gherkin. Entregue o veredito: PRONTA, REFINAR com números de perguntas que a desbloqueiam, ou BLOQUEADA com justificativa. Se [DECOMPOSE] estiver presente, inclua a proposta de decomposição: narrativa para cada parte e mapeamento dos critérios originais. Concluído quando: o arquivo existe no caminho definido por docs/agents/refinement.md, com Status: correspondente ao veredito e o aviso final presente.

7. Roteirizar itens abertos. Para cada destinatário fora da sessão com [TO CONFIRM], escreva um questionário seguindo QUESTIONNAIRE.md em requirements-rigor, junto com a HU refinada, e vincule o arquivo da seção de perguntas abertas. Concluído quando: nenhum [TO CONFIRM] permanece sem um destinatário ou questionário.

8. Relatar. Informe o usuário de forma concisa: veredito, onde a HU foi publicada, quais perguntas a desbloqueiam e questionários gerados.

Exemplo de rodada

Para a HU "Como usuário, quero exportar relatórios para PDF para facilitar o compartilhamento. CR1: botão de exportar deve funcionar corretamente. CR2: criar serviço de geração de PDF no backend. CR3: PDF deve abrir rápido. CR4: código revisado e testes passando.", em um workspace sem código cujo glossário lista analista operacional e gerente de conta como consumidores de relatórios, a primeira rodada se parece com:

❓ P1. Quem exporta? (bloqueante) A narrativa diz "usuário". O glossário lista analista operacional e gerente de conta como papéis que consomem relatórios. Qual papel exporta, ou ambos? Recomendação: analista operacional [INFERÊNCIA: papel associado a "relatórios operacionais" no glossário]. Sem isso, as permissões permanecem indefinidas e a narrativa falha no INVEST.

❓ P2. O que significa "abrir rápido"? (bloqueante) CR3 não é testável e admite duas leituras: tempo entre acionar a exportação e o download começar, ou tempo para o arquivo abrir em um leitor. Qual é a intenção e qual é o tempo máximo em segundos? Recomendação: sem recomendação: o texto fonte não fornece base para interpretação ou números de SLA. Se não houver expectativa, registre [TO CONFIRM: PO] e prossiga.

❓ P3. Casos de borda A fonte sugere relatórios vazios e relatórios de alto volume [INFERÊNCIA: relatórios variam em volume]. Quais importam para esta entrega? Recomendação: inclua ambos como cenários [INFERÊNCIA: seguem do texto fonte]. O comportamento específico para cada um é sua decisão: sem recomendação. O volume máximo depende da P2.

CR2 e CR4 não disparam perguntas: CR2 é uma tarefa de implementação cujo comportamento habilitado é coberto por CR1, movendo para notas; CR4 é Definição de Pronto da equipe e é removido dos critérios. Ambos aparecem na seção de auditoria do artefato final como movidos, não excluídos.

Aviso final

Todo artefato publicado conclui com:

⚠️ Esta saída é preparação para refinamento, não uma substituição. Decisões sobre escopo, valor e prioridade pertencem estritamente ao PO e à equipe.