Entrada do Usuário
$ARGUMENTS
Você DEVE considerar a entrada do usuário antes de prosseguir (se não estiver vazia).
Verificações Pré-Execução
Verificar ganchos de extensão (antes do esclarecimento):
- Verifique se
.specify/extensions.ymlexiste na raiz do projeto. - Se existir, leia-o e procure por entradas sob a chave
hooks.before_clarify. - Se o YAML não puder ser analisado ou for inválido, não ignore silenciosamente: informe ao usuário que
.specify/extensions.ymlnão pôde ser lido (inclua o erro do analisador) e que nenhum gancho foi verificado, incluindo quaisquer ganchos obrigatórios (optional: false) registrados ali; em seguida, continue normalmente. - Filtre ganchos onde
enabledé explicitamentefalse. Trate ganchos sem um campoenabledcomo habilitados por padrão. - Para cada gancho restante, não tente interpretar ou avaliar expressões de
conditiondo gancho:- Se o gancho não tiver um campo
condition, ou ele for nulo/vazio, trate o gancho como executável. - Se o gancho definir uma
conditionnão vazia, pule o gancho e deixe a avaliação da condição para a implementação do HookExecutor.
- Se o gancho não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando de gancho, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada gancho executável, produza o seguinte com base em sua flag
optional:- Gancho opcional (
optional: true):## Ganchos de Extensão **Pré-Gancho Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}` - Gancho obrigatório (
optional: false):
Após emitir o bloco acima, você DEVE realmente invocar o gancho e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando você mesmo neste agente/sessão (a invocação pode diferir do id literal## Ganchos de Extensão **Pré-Gancho Automático**: {extensão} Executando: `/{comando}` EXECUTE_COMMAND: {comando} Aguarde o resultado do comando do gancho antes de prosseguir para o Esboço.{comando}mostrado acima, por exemplo, um agente em modo de skills o executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o gancho.
- Gancho opcional (
- Se nenhum gancho estiver registrado ou
.specify/extensions.ymlnão existir, ignore silenciosamente.
Esboço
Objetivo: Detectar e reduzir ambiguidades ou pontos de decisão ausentes na especificação do recurso ativo e registrar os esclarecimentos diretamente no arquivo de especificação.
Nota: Espera-se que este fluxo de trabalho de esclarecimento seja executado (e concluído) ANTES de invocar /speckit-plan. Se o usuário declarar explicitamente que está pulando o esclarecimento (por exemplo, pico exploratório), você pode prosseguir, mas deve avisar que o risco de retrabalho downstream aumenta.
Passos de execução:
-
Execute
.specify/scripts/bash/check-prerequisites.sh --json --paths-onlyda raiz do repositório uma vez (modo combinado--json --paths-only/-Json -PathsOnly). Analise os campos mínimos do payload JSON:FEATURE_DIRFEATURE_SPEC- (Opcionalmente, capture
IMPL_PLAN,TASKSpara fluxos encadeados futuros.) - Se a análise JSON falhar, aborta e instrua o usuário a executar novamente
/speckit-specifyou verificar o ambiente do branch do recurso. - Para aspas simples em argumentos como "Estou bem", use sintaxe de escape: por exemplo, 'Estou'''bem' (ou aspas duplas se possível: "Estou bem").
-
SE EXISTIR: Carregue
.specify/memory/constitution.mdpara obter princípios do projeto e restrições de governança. -
Carregue o arquivo de especificação atual. Realize uma varredura estruturada de ambiguidade e cobertura usando esta taxonomia. Para cada categoria, marque o status: Claro / Parcial / Ausente. Produza um mapa de cobertura interno usado para priorização (não produza o mapa bruto a menos que nenhuma pergunta seja feita).
Escopo Funcional e Comportamento:
- Objetivos principais do usuário e critérios de sucesso
- Declarações explícitas de fora do escopo
- Funções de usuário / diferenciação de personas
Domínio e Modelo de Dados:
- Entidades, atributos, relacionamentos
- Regras de identidade e unicidade
- Transições de ciclo de vida/estado
- Suposições de volume de dados / escala
Interação e Fluxo de UX:
- Jornadas/sequências críticas do usuário
- Estados de erro/vazio/carregamento
- Notas de acessibilidade ou localização
Atributos de Qualidade Não Funcionais:
- Desempenho (metas de latência, throughput)
- Escalabilidade (horizontal/vertical, limites)
- Confiabilidade e disponibilidade (uptime, expectativas de recuperação)
- Observabilidade (sinais de logging, métricas, tracing)
- Segurança e privacidade (authN/Z, proteção de dados, suposições de ameaça)
- Restrições de conformidade / regulatórias (se houver)
Integração e Dependências Externas:
- Serviços/APIs externos e modos de falha
- Formatos de importação/exportação de dados
- Suposições de protocolo/versionamento
Casos Extremos e Tratamento de Falhas:
- Cenários negativos
- Limitação de taxa / throttling
- Resolução de conflitos (por exemplo, edições concorrentes)
Restrições e Tradeoffs:
- Restrições técnicas (linguagem, armazenamento, hospedagem)
- Tradeoffs explícitos ou alternativas rejeitadas
Terminologia e Consistência:
- Termos canônicos do glossário
- Sinônimos evitados / termos obsoletos
Sinais de Conclusão:
- Testabilidade dos critérios de aceitação
- Indicadores mensuráveis no estilo Definição de Pronto
Diversos / Espaços Reservados:
- Marcadores TODO / decisões não resolvidas
- Adjetivos ambíguos ("robusto", "intuitivo") sem quantificação
Para cada categoria com status Parcial ou Ausente, adicione uma oportunidade de pergunta candidata, a menos que:
- O esclarecimento não altere materialmente a estratégia de implementação ou validação
- O item seja especificamente sobre método de implementação, comparação de pilha tecnológica ou detalhamento de tarefas (anote internamente)
-
Gere (internamente) uma fila priorizada de perguntas de esclarecimento candidatas (máximo de 5). NÃO as produza todas de uma vez. Aplique estas restrições:
- Máximo de 5 perguntas no total em toda a sessão.
- Cada pergunta deve ser respondível com:
- Uma seleção de múltipla escolha curta (2 a 5 opções distintas e mutuamente exclusivas), OU
- Uma resposta de uma palavra / frase curta (restrinja explicitamente: "Responda em <=5 palavras").
- Inclua apenas perguntas cujas respostas impactem materialmente arquitetura, modelagem de dados, decomposição de tarefas, design de testes, comportamento de UX, prontidão operacional ou validação de conformidade.
- Garanta equilíbrio de cobertura de categoria: tente cobrir primeiro as categorias não resolvidas de maior impacto; evite fazer duas perguntas de baixo impacto quando uma única área de alto impacto (por exemplo, postura de segurança) não estiver resolvida.
- Exclua perguntas já respondidas, preferências estilísticas triviais ou detalhes de execução no nível do plano (a menos que bloqueiem a correção).
- Favoreça esclarecimentos que reduzam o risco de retrabalho downstream ou evitem testes de aceitação desalinhados.
- Se mais de 5 categorias permanecerem não resolvidas, selecione as 5 principais pela heurística (Impacto * Incerteza).
-
Loop de perguntas sequenciais (interativo):
-
Apresente EXATAMENTE UMA pergunta por vez.
-
Qualidade da redação da pergunta (aplica-se a cada pergunta, de múltipla escolha ou resposta curta):
- Comece com
**Pergunta:**seguido de uma interrogativa completa que termine com?. O texto da pergunta antes do?deve fazer sentido por si só. - NUNCA use um rótulo de tópico, cabeçalho de seção ou id de requisito como a própria pergunta. Por exemplo,
Matriz de dispositivo/tempo de execução de aceitação (FR-023)é INVÁLIDO — é um rótulo, não uma pergunta. - Após o
?, o único sufixo permitido é um id de requisito/pergunta opcional entre parênteses. Formato exato:**Pergunta:** <interrogativa>?ou**Pergunta:** <interrogativa>? (FR-023). Nunca coloque o id antes do?e nunca use o id (sozinho ou com um rótulo de tópico) como todo o prompt. - Imediatamente após a linha da pergunta, adicione uma frase em linguagem simples explicando "Por que isso é importante" (o impacto para aceitação ou lançamento) antes da recomendação/opções.
- Use redação cotidiana; introduza jargão apenas se definido na mesma frase. Autoverificação: um leitor que não conhece o Spec Kit deve ser capaz de responder apenas pela linha da Pergunta. Conciso é aceitável; rótulos enigmáticos não são.
- Comece com
-
Para perguntas de múltipla escolha:
- Analise todas as opções e determine a opção mais adequada com base em:
- Melhores práticas para o tipo de projeto
- Padrões comuns em implementações semelhantes
- Redução de risco (segurança, desempenho, manutenibilidade)
- Alinhamento com quaisquer metas ou restrições explícitas do projeto visíveis na especificação
- Apresente sua opção recomendada proeminentemente no topo com uma justificativa clara (1-2 frases explicando por que esta é a melhor escolha).
- Formate como:
**Recomendado:** Opção [X] - <justificativa> - Em seguida, renderize todas as opções como uma tabela Markdown:
Opção Descrição A <Descrição da Opção A> B <Descrição da Opção B> C <Descrição da Opção C> (adicione D/E conforme necessário até 5) Personalizado Forneça uma resposta personalizada diferente (<=5 palavras) (Inclua apenas se uma alternativa de formato livre for apropriada) - Após a tabela, adicione:
Você pode responder com a letra da opção (ex.: "A"), aceitar a recomendação dizendo "sim" ou "recomendado", ou fornecer sua própria resposta personalizada.
- Analise todas as opções e determine a opção mais adequada com base em:
-
Para estilo de resposta curta (sem opções discretas significativas):
- Forneça sua resposta sugerida com base nas melhores práticas e no contexto.
- Formate como:
**Sugerido:** <sua resposta proposta> - <breve justificativa> - Em seguida, produza:
Formato: Resposta curta (<=5 palavras). Você pode aceitar a sugestão dizendo "sim" ou "sugerido", ou fornecer sua própria resposta.
-
Após o usuário responder:
- Se o usuário responder com "sim", "recomendado" ou "sugerido", use sua recomendação/sugestão declarada anteriormente como a resposta.
- Caso contrário, valide se a resposta corresponde a uma opção ou se encaixa na restrição de <=5 palavras.
- Se ambígua, peça um rápido esclarecimento (a contagem ainda pertence à mesma pergunta; não avance).
- Uma vez satisfatório, registre-a na memória de trabalho (ainda não grave em disco) e passe para a próxima pergunta na fila.
-
Pare de fazer mais perguntas quando:
- Todas as ambiguidades críticas forem resolvidas precocemente (os itens restantes na fila se tornarem desnecessários), OU
- O usuário sinalizar conclusão ("pronto", "bom", "chega"), OU
- Você atingir 5 perguntas feitas.
-
Nunca revele perguntas futuras na fila com antecedência.
-
Se nenhuma pergunta válida existir no início, relate imediatamente que não há ambiguidades críticas.
-
-
Integração após CADA resposta aceita (abordagem de atualização incremental):
- Mantenha a representação em memória da especificação (carregada uma vez no início) mais o conteúdo bruto do arquivo.
- Para a primeira resposta integrada nesta sessão:
- Garanta que uma seção
## Esclarecimentosexista (crie-a logo após a seção contextual/visão geral de nível mais alto, de acordo com o modelo de especificação, se estiver faltando). - Sob ela, crie (se não estiver presente) um subtítulo
### Sessão YYYY-MM-DDpara hoje.
- Garanta que uma seção
- Anexe uma linha de marcador imediatamente após a aceitação:
- P: <pergunta> → R: <resposta final>. - Em seguida, aplique imediatamente o esclarecimento à(s) seção(ões) mais apropriada(s):
- Ambiguidade funcional → Atualize ou adicione um marcador em Requisitos Funcionais.
- Interação do usuário / distinção de ator → Atualize Histórias de Usuário ou a subseção de Atores (se presente) com função, restrição ou cenário esclarecidos.
- Forma dos dados / entidades → Atualize o Modelo de Dados (adicione campos, tipos, relacionamentos) preservando a ordenação; anote novas restrições de forma sucinta.
- Restrição não funcional → Adicione/modifique critérios mensuráveis em Critérios de Sucesso > Resultados Mensuráveis (converta adjetivo vago em métrica ou alvo explícito).
- Caso extremo / fluxo negativo → Adicione um novo marcador em Casos Extremos / Tratamento de Erros (ou crie essa subseção se o modelo fornecer um espaço reservado para ela).
- Conflito de terminologia → Normalize o termo em toda a especificação; mantenha o original apenas se necessário, adicionando
(anteriormente referido como "X")uma vez.
- Se o esclarecimento invalidar uma declaração ambígua anterior, substitua essa declaração em vez de duplicar; não deixe texto contraditório obsoleto.
- Salve o arquivo de especificação APÓS cada integração para minimizar o risco de perda de contexto (sobrescrita atômica).
- Preserve a formatação: não reordene seções não relacionadas; mantenha a hierarquia de cabeçalhos intacta.
- Mantenha cada esclarecimento inserido mínimo e testável (evite desvios narrativos).
-
Validação (realizada APÓS cada gravação mais uma passada final):
- A sessão de esclarecimentos contém exatamente um marcador por resposta aceita (sem duplicatas).
- Total de perguntas feitas (aceitas) ≤ 5.
- As seções atualizadas não contêm espaços reservados vagos persistentes que a nova resposta deveria resolver.
- Nenhuma declaração contraditória anterior permanece (verifique se não há escolhas alternativas agora inválidas removidas).
- Estrutura Markdown válida; apenas novos cabeçalhos permitidos:
## Esclarecimentos,### Sessão YYYY-MM-DD. - Consistência de terminologia: mesmo termo canônico usado em todas as seções atualizadas.
-
Grave a especificação atualizada de volta em
FEATURE_SPEC. -
Revalidar a Lista de Verificação de Qualidade da Especificação (se existir):
- Verifique se
FEATURE_DIR/checklists/requirements.mdexiste. - Se NÃO existir, pule esta etapa silenciosamente.
- Se existir:
- Leia o arquivo da lista de verificação.
- Identifique todas as linhas de caixa de seleção de lista de tarefas do GitHub — linhas correspondentes a
- [ ],- [x]ou- [X](insensível a maiúsculas/minúsculas, tolerante a espaços em branco iniciais para itens aninhados) fora de blocos de código. Ignore todo o resto (cabeçalhos, notas, marcadores que não são caixas de seleção, metadados). - Para cada linha de caixa de seleção, registre seu estado de marcador atual (marcado ou desmarcado) e o texto do item em uma lista de instantâneo anterior.
- Reavalie cada item da caixa de seleção em relação à especificação atualizada (a versão recém-salva na etapa 7).
- Para cada item da caixa de seleção, atualize apenas se o estado marcado/desmarcado realmente mudar:
- Se o item agora for aprovado e estava desmarcado: mude
[ ]para[x]. - Se o item agora falhar e estava marcado: mude
[x]/[X]para[ ]. - Se o estado não mudar: deixe como está.
- Se o item agora for aprovado e estava desmarcado: mude
- Registre as alterações reais (se houver) gravando o arquivo atualizado.
- Se alguma caixa de seleção mudou, forneça um resumo da alteração: liste o texto do item e a transição de estado (por exemplo,
- [ ] Confirme a arquitetura de segurança → [x]). Se nenhuma caixa de seleção mudou, nenhuma saída é necessária (exceto se você estiver relatando progresso para o usuário em uma conversa).
- Verifique se