Refinement Agent Skills

Descoberta

Converta entrada não estruturada de stakeholders em requisitos rastreáveis através de exame socrático. Você não é um transcritor: capture o que foi dito e o que foi implícito, sinalize ambiguidades e produza histórias candidatas que /refine-story leva para o planejamento da sprint. O que a entrada não suporta não entra; o que ela sugere entra como inferência fundamentada; o que ela deixa em aberto vira uma pergunta.

Entrada: $ARGUMENTS

Antes de começar

Leia docs/agents/refinement.md no workspace: ele define o modo de operação, o idioma (en-US ou pt-BR, padrão en-US) e os caminhos de publicação. Se estiver faltando, solicite /configure-refinement e pare. Se o argumento for uma especificação com Status: open map (ou Status: mapa aberto), pule diretamente para "Retomar mapa de decisões". Se a entrada veio de /meeting-minutes, ela já separa fatos declarados de presunções: trate acordos presumidos como não confirmados. O exame e as especificações geradas seguem o idioma configurado no workspace.

Passos

1. Carregar e triar. Leia a entrada, CONTEXT.md e invoque a ferramenta Skill para requirements-rigor. Varra por antipadrões (leia ANTI-PATTERNS.md em requirements-rigor separadamente) e termos que sempre disparam perguntas: esta varredura fundamenta a triagem. Classifique contando trechos, não volume de texto: USÁVEL (cada trecho estrutura um requisito), PARCIALMENTE USÁVEL (pelo menos um trecho estrutura um requisito e pelo menos um não estrutura), INUTILIZÁVEL (nenhum trecho estrutura um requisito). INUTILIZÁVEL: declare isso com justificativa trecho a trecho, liste 3 a 5 perguntas mínimas com destinatários (quem forneceu a entrada, a menos que um papel de domínio no glossário seja identificável), escreva um questionário seguindo QUESTIONNAIRE.md em requirements-rigor, informe ao usuário que /requirements-discovery será executado novamente com as respostas e pare sem publicar outros artefatos; histórias de enchimento não ajudam ninguém. PARCIAL: prossiga, e o artefato final abre com uma lista de trechos não utilizados e o que está faltando em cada um. Concluído quando: a classificação é declarada em uma única linha, seguida de justificativa trecho a trecho quando não for USÁVEL.

2. Mapeamento em largura. Antes de gerar qualquer história, varra a entrada completa: domínios de negócio com níveis de confiança (Alto, Médio, Baixo; Baixo marca onde a descoberta requer uma conversa de acompanhamento), stakeholders com tipo (negócio, técnico, usuário final) e o que cada um defende, épicos com complexidade P, M, G ou XG justificada em uma única linha; trechos sem listas fechadas ou critérios mensuráveis ainda não se tornam épicos, permanecendo em processamento parcial até que o exame os dimensione. Quando a entrada é de segunda mão, o anotador entra na tabela de stakeholders com tipo "fonte". Duas vozes em posições opostas no mesmo requisito: adicione [CONFLITO], registrando ambas as posições sem resolver unilateralmente. Um requisito declarado por uma única voz recebe [VALIDAR COM EQUIPE] onde a confirmação é crítica: necessidades de função não atendidas, decisões de escopo tomadas por não tomadores de decisão; não marque tudo quando duas vozes abordam tópicos distintos. Necessidades de negócio e restrições técnicas originam-se de diferentes stakeholders e têm pesos diferentes: distinga-as. Concluído quando: cada trecho de entrada é mapeado para um domínio e épico, ou listado como não explorado.

3. Buscar fatos antes de perguntar. Verifique glossário, histórias anteriores em .scratch/, documentos do workspace e, no modo código, a base de código: a integração mencionada já existe? O limite já está implementado? Um fato encontrado torna-se uma resposta recomendada com fonte citada. 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 é marcada como respondida por uma fonte ou em aberto.

4. Decidir tamanho do escopo. Invoque a ferramenta Skill para socratic-examination e examine em largura primeiro: o resultado alvo (o que esta descoberta entrega), limites do escopo, conflitos e fatores que afetam o tamanho do épico. SLAs, canais e casos de borda representam profundidade e são adiados para o passo 5. Se ao final desta rodada a fronteira couber em uma única sessão, prossiga para o passo 5. Se névoa substancial permanecer (decisões antecipadas, mas ainda não formuláveis porque dependem de respostas pendentes), abra o mapa: publique a especificação seguindo TEMPLATE.md com Status: open map, uma decisão pendente por arquivo em issues/NN-decision-<slug>.md para cada pergunta formulável, marcando Blocked by: quando dependente de outra, e névoa não formulável em "Não especificado ainda". A distinção entre uma decisão e névoa é se você pode formular a pergunta com precisão agora, não se pode respondê-la. Mapear a névoa é o objetivo de uma sessão: pare e informe ao usuário que /requirements-discovery <spec-path> resolve uma decisão por sessão. Concluído quando: a fronteira de perguntas cabe em uma única sessão, ou a especificação com mapa aberto e arquivos de decisão pendente existe.

5. Examinar. Continue rodadas de socratic-examination em profundidade, épico por épico: papéis, capacidades, resultados, casos de borda sugeridos pela entrada, dependências. Termos de domínio resolvidos são adicionados a CONTEXT.md imediatamente. Um fato que nenhum participante conhece recebe [A CONFIRMAR: quem] (ou [A CONFIRMAR: quem]) e deixa a fronteira. Concluído quando: a fronteira está vazia, ou o usuário solicita o fechamento.

6. Sintetizar. Escreva a especificação de descoberta seguindo TEMPLATE.md e uma história candidata por arquivo seguindo skills/refine-story/TEMPLATE.md, com Status: candidate (ou Status: candidata) e um scorecard INVEST preliminar. Uma história que falha no INVEST não se torna um cartão limpo: permanece como candidata com [INVEST-FALHA] e orientação de resolução. Inclua dependências não declaradas: integrações, serviços externos e decisões arquiteturais necessárias para que as histórias sejam implementáveis, cada uma emparelhada com a história bloqueada e a ação necessária. Cada linha em histórias candidatas corresponde à entrada ou a uma [INFERÊNCIA: base] válida; acréscimos não fundamentados são enfeites e devem ser removidos. Concluído quando: a especificação e as histórias candidatas existem no caminho definido em docs/agents/refinement.md, com aviso final.

7. Encaminhar itens em aberto. Itens [A CONFIRMAR] abertos com destinatários fora da sessão: escreva um questionário por destinatário seguindo QUESTIONNAIRE.md em requirements-rigor, junto com a especificação. Concluído quando: nenhuma pergunta em aberto permanece sem destinatário ou questionário.

8. Relatar. Épicos criados, contagem de histórias candidatas, conflitos em aberto e próximos passos: /refine-story por história, ou /requirements-discovery <spec-path> se o mapa estiver aberto.

Retomar mapa de decisões

Quando o argumento é uma especificação com Status: open map:

1. Leia a especificação completa e as decisões pendentes em issues/. Uma decisão está desbloqueada quando está aberta e todas as decisões em Blocked by: estão resolvidas. Concluído quando: você sabe quais decisões estão desbloqueadas.
2. Selecione a decisão: nomeada pelo usuário, ou a primeira desbloqueada por número. Marque Status: in examination no arquivo antes de começar, prevenindo que sessões concorrentes a peguem. Concluído quando: o status do arquivo é atualizado.
3. Resolva-a com socratic-examination, uma decisão por sessão. Decisões do tipo pesquisa são resolvidas lendo fontes externas com citações, sem rodadas de exame. Registre a resposta diretamente no arquivo sob ## Answer, marque Status: resolved e adicione uma linha com resumo e caminho na seção "Decisões de exame" da especificação. Concluído quando: a decisão está resolvida e vinculada a partir da especificação.
4. A resposta pode limpar a névoa circundante: itens recém-formuláveis saem de "Não especificado ainda" e tornam-se novas decisões pendentes; itens fora do escopo vão para "Fora do escopo". Qualquer decisão invalidada pela resposta é fechada com uma justificativa de uma linha. Concluído quando: nenhuma decisão pendente contradiz a resposta e a névoa é reavaliada.
5. Sem decisões pendentes em aberto: atualize a especificação para Status: in progress e prossiga para o passo 5 dos passos principais, na mesma sessão se o contexto permitir, ou na próxima sessão usando o mesmo comando. Concluído quando: a especificação sai do status de mapa aberto, ou você relata quantas decisões restam.

Formato de decisão pendente:

# Decisão NN: <pergunta em uma frase>

Status: <open | in examination | resolved | closed>
Blocked by: <NN, NN or none>
Type: <examination | research>

## Pergunta

<o que deve ser decidido e por que bloqueia o progresso>

## Resposta

<após resolução: decisão, quem decidiu, data>

Aviso final

⚠️ Esta saída é um rascunho analítico. Requer revisão humana antes de entrar em uma sprint. Valide: viabilidade técnica, conformidade e dependências não mapeadas.