Entrada do Usuário
$ARGUMENTS
Você DEVE considerar a entrada do usuário antes de prosseguir (se não estiver vazia).
Verificações de Pré-Execução
Verificar hooks de extensão (antes da análise):
- Verifique se o arquivo
.specify/extensions.ymlexiste na raiz do projeto. - Se existir, leia-o e procure por entradas sob a chave
hooks.before_analyze - 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 hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados lá, então continue normalmente - Filtre hooks onde
enabledé explicitamentefalse. Trate hooks sem um campoenabledcomo habilitados por padrão. - Para cada hook restante, não tente interpretar ou avaliar expressões de
conditiondo hook:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor
- Se o hook não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando do hook, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook executável, produza o seguinte com base em sua flag
optional:- Hook opcional (
optional: true):## Extension Hooks **Pre-Hook Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}` - Hook obrigatório (
optional: false):
Após emitir o bloco acima, você DEVE realmente invocar o hook e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando neste agente/sessão (a invocação pode diferir do## Extension Hooks **Pre-Hook Automático**: {extensão} Executando: `/{comando}` EXECUTE_COMMAND: {comando} Aguarde o resultado do comando do hook antes de prosseguir para o Objetivo.{comando}literal mostrado acima, por exemplo, um agente em modo skills o executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o hook.
- Hook opcional (
- Se nenhum hook estiver registrado ou
.specify/extensions.ymlnão existir, ignore silenciosamente
Objetivo
Identificar inconsistências, duplicações, ambiguidades e itens subespecificados nos três artefatos principais (spec.md, plan.md, tasks.md) antes da implementação. Este comando DEVE ser executado somente após /speckit-tasks ter produzido com sucesso um tasks.md completo.
Restrições Operacionais
ESTRITAMENTE SOMENTE LEITURA: Não modifique nenhum arquivo. Produza um relatório de análise estruturado. Ofereça um plano de remediação opcional (o usuário deve aprovar explicitamente antes que quaisquer comandos de edição de acompanhamento sejam invocados manualmente).
Autoridade da Constituição: A constituição do projeto (.specify/memory/constitution.md) é innegociável dentro deste escopo de análise. Conflitos com a constituição são automaticamente CRÍTICOS e exigem ajuste do spec, plano ou tarefas — não diluição, reinterpretação ou ignorância silenciosa do princípio. Se um princípio em si precisar ser alterado, isso deve ocorrer em uma atualização separada e explícita da constituição, fora de /speckit-analyze.
Passos de Execução
1. Inicializar Contexto de Análise
Execute .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks uma vez a partir da raiz do repositório e analise o JSON para obter FEATURE_DIR e AVAILABLE_DOCS. Derive caminhos absolutos:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
Aborte com uma mensagem de erro se algum arquivo obrigatório estiver ausente (instrua o usuário a executar o comando pré-requisito ausente). Para aspas simples em argumentos como "I'm Groot", use sintaxe de escape: por exemplo, 'I'''m Groot' (ou aspas duplas, se possível: "I'm Groot").
2. Carregar Artefatos (Divulgação Progressiva)
Carregue apenas o contexto mínimo necessário de cada artefato:
Do spec.md:
- Visão Geral/Contexto
- Requisitos Funcionais
- Critérios de Sucesso (resultados mensuráveis — por exemplo, desempenho, segurança, disponibilidade, sucesso do usuário, impacto nos negócios)
- Histórias de Usuário
- Casos Extremos (se presentes)
Do plan.md:
- Escolhas de arquitetura/stack
- Referências ao Modelo de Dados
- Fases
- Restrições técnicas
Do tasks.md:
- IDs de Tarefas
- Descrições
- Agrupamento por fase
- Marcadores paralelos [P]
- Caminhos de arquivos referenciados
Da constituição:
- Carregue
.specify/memory/constitution.mdpara validação de princípios
3. Construir Modelos Semânticos
Crie representações internas (não inclua artefatos brutos na saída):
- Inventário de requisitos: Para cada Requisito Funcional (FR-###) e Critério de Sucesso (SC-###), registre uma chave estável. Use o identificador explícito FR-/SC- como chave primária quando presente e, opcionalmente, derive também um slug de frase imperativa para legibilidade (por exemplo, "Usuário pode enviar arquivo" →
usuario-pode-enviar-arquivo). Inclua apenas itens de Critério de Sucesso que exijam trabalho construível (por exemplo, infraestrutura de teste de carga, ferramentas de auditoria de segurança) e exclua métricas de resultado pós-lançamento e KPIs de negócios (por exemplo, "Reduzir tickets de suporte em 50%"). - Inventário de histórias/ações de usuário: Ações discretas do usuário com critérios de aceitação
- Mapeamento de cobertura de tarefas: Mapeie cada tarefa para um ou mais requisitos ou histórias (inferência por palavra-chave / padrões de referência explícita como IDs ou frases-chave)
- Conjunto de regras da constituição: Extraia nomes de princípios e declarações normativas DEVE/DEVERIA
4. Passos de Detecção (Análise Eficiente em Tokens)
Foque em descobertas de alto sinal. Limite a 50 descobertas no total; agregue o restante em um resumo de excesso.
A. Detecção de Duplicação
- Identifique requisitos quase duplicados
- Marque frases de qualidade inferior para consolidação
B. Detecção de Ambiguidade
- Sinalize adjetivos vagos (rápido, escalável, seguro, intuitivo, robusto) sem critérios mensuráveis
- Sinalize espaços reservados não resolvidos (TODO, TKTK, ???,
<placeholder>, etc.)
C. Subespecificação
- Requisitos com verbos, mas sem objeto ou resultado mensurável
- Histórias de usuário sem alinhamento de critérios de aceitação
- Tarefas referenciando arquivos ou componentes não definidos no spec/plano
D. Alinhamento com a Constituição
- Qualquer requisito ou elemento do plano em conflito com um princípio DEVE
- Seções obrigatórias ou portões de qualidade ausentes da constituição
E. Lacunas de Cobertura
- Requisitos com zero tarefas associadas
- Tarefas sem requisito/história mapeado
- Critérios de Sucesso que exigem trabalho construível (desempenho, segurança, disponibilidade) não refletidos nas tarefas
F. Inconsistência
- Deriva de terminologia (mesmo conceito nomeado de forma diferente entre arquivos)
- Entidades de dados referenciadas no plano, mas ausentes no spec (ou vice-versa)
- Contradições na ordenação de tarefas (por exemplo, tarefas de integração antes de tarefas de configuração fundamental sem nota de dependência)
- Requisitos conflitantes (por exemplo, um requer Next.js enquanto outro especifica Vue)
5. Atribuição de Severidade
Use esta heurística para priorizar descobertas:
- CRÍTICO: Viola o DEVE da constituição, artefato spec principal ausente, ou requisito com cobertura zero que bloqueia a funcionalidade básica
- ALTO: Requisito duplicado ou conflitante, atributo de segurança/desempenho ambíguo, critério de aceitação não testável
- MÉDIO: Deriva de terminologia, cobertura de tarefas não funcional ausente, caso extremo subespecificado
- BAIXO: Melhorias de estilo/redação, redundância menor que não afeta a ordem de execução
6. Produzir Relatório de Análise Compacto
Produza um relatório em Markdown (sem gravação de arquivos) com a seguinte estrutura:
Relatório de Análise de Especificação
| ID | Categoria | Severidade | Local(is) | Resumo | Recomendação |
|---|---|---|---|---|---|
| A1 | Duplicação | ALTO | spec.md:L120-134 | Dois requisitos semelhantes ... | Mesclar redação; manter versão mais clara |
(Adicione uma linha por descoberta; gere IDs estáveis prefixados pela inicial da categoria.)
Tabela de Resumo de Cobertura:
| Chave do Requisito | Tem Tarefa? | IDs de Tarefas | Notas |
|---|
Problemas de Alinhamento com a Constituição: (se houver)
Tarefas Não Mapeadas: (se houver)
Métricas:
- Total de Requisitos
- Total de Tarefas
- Cobertura % (requisitos com >=1 tarefa)
- Contagem de Ambiguidade
- Contagem de Duplicação
- Contagem de Problemas Críticos
7. Fornecer Próximas Ações
Ao final do relatório, produza um bloco conciso de Próximas Ações:
- Se existirem problemas CRÍTICOS: Recomende resolver antes de
/speckit-implement - Se apenas BAIXO/MÉDIO: O usuário pode prosseguir, mas forneça sugestões de melhoria
- Forneça sugestões explícitas de comando: por exemplo, "Execute /speckit-specify com refinamento", "Execute /speckit-plan para ajustar arquitetura", "Edite manualmente tasks.md para adicionar cobertura para 'metricas-de-desempenho'"
8. Oferecer Remediação
Pergunte ao usuário: "Gostaria que eu sugerisse edições de remediação concretas para os principais N problemas?" (Não os APLIQUE automaticamente.)
9. Verificar hooks de extensão
Após o relatório, verifique se o arquivo .specify/extensions.yml existe na raiz do projeto.
- Se existir, leia-o e procure por entradas sob a chave
hooks.after_analyze - 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 hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados lá, então continue normalmente - Filtre hooks onde
enabledé explicitamentefalse. Trate hooks sem um campoenabledcomo habilitados por padrão. - Para cada hook restante, não tente interpretar ou avaliar expressões de
conditiondo hook:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor
- Se o hook não tiver um campo
- Ao construir invocações de comando a partir de nomes de comando do hook, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook executável, produza o seguinte com base em sua flag
optional:- Hook opcional (
optional: true):## Extension Hooks **Hook Opcional**: {extensão} Comando: `/{comando}` Descrição: {descrição} Prompt: {prompt} Para executar: `/{comando}` - Hook obrigatório (
optional: false):
Após emitir o bloco acima, você DEVE realmente invocar o hook e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando neste agente/sessão (a invocação pode diferir do## Extension Hooks **Hook Automático**: {extensão} Executando: `/{comando}` EXECUTE_COMMAND: {comando}{comando}literal mostrado acima, por exemplo, um agente em modo skills o executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o hook.
- Hook opcional (
- Se nenhum hook estiver registrado ou
.specify/extensions.ymlnão existir, ignore silenciosamente
Princípios Operacionais
Eficiência de Contexto
- Tokens mínimos de alto sinal: Foque em descobertas acionáveis, não em documentação exaustiva
- Divulgação progressiva: Carregue artefatos incrementalmente; não despeje todo o conteúdo na análise
- Saída eficiente em tokens: Limite a tabela de descobertas a 50 linhas; resuma o excesso
- Resultados determinísticos: Reexecutar sem alterações deve produzir IDs e contagens consistentes
Diretrizes de Análise
- NUNCA modifique arquivos (esta é uma análise somente leitura)
- NUNCA alucine seções ausentes (se ausentes, relate-as com precisão)
- Priorize violações da constituição (estas são sempre CRÍTICAS)
- Use exemplos em vez de regras exaustivas (cite instâncias específicas, não padrões genéricos)
- Relate zero problemas graciosamente (emita um relatório de sucesso com estatísticas de cobertura)
Contexto
$ARGUMENTS