Communitygithub.com

tangjuyo/reels-blocker

Identifique áreas subespecificadas na especificação atual do recurso fazendo até 5 perguntas de esclarecimento altamente direcionadas e codificando as respostas de volta na especificação.

O que é reels-blocker?

Esta skill do agente atua como um analisador de especificações para identificar ambiguidades, pontos de decisão ausentes e áreas subespecificadas em um documento de especificação de recurso de software. Ela carrega a especificação atual (geralmente gerada por uma ferramenta como o Spec Kit), realiza uma varredura estruturada usando uma taxonomia detalhada que abrange escopo funcional, modelo de dados, UX, atributos não funcionais, integrações, casos extremos e terminologia. Com base nessa varredura, ela gera uma fila priorizada de no máximo 5 perguntas de esclarecimento, cada uma projetada para ser respondida como múltipla escolha (2 a 5 opções) ou resposta curta (<=5 palavras). A skill então faz uma pergunta por vez de forma interativa, apresenta uma recomendação com justificativa, aguarda a resposta do usuário e integra imediatamente cada esclarecimento na especificação, atualizando seções relevantes (requisitos, modelo de dados, critérios de sucesso, etc.). Após cada integração, ela salva o arquivo da especificação e valida as alterações para consistência e conformidade com a estrutura de markdown, garantindo que o documento final seja mais preciso, testável e pronto para implementação.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-clarify

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.yml existe 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.yml nã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 é explicitamente false. Trate ganchos sem um campo enabled como habilitados por padrão.
  • Para cada gancho restante, não tente interpretar ou avaliar expressões de condition do 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 condition não vazia, pule o gancho e deixe a avaliação da condição para a implementação do HookExecutor.
  • 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):
      ## 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.
      
      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 {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.
  • Se nenhum gancho estiver registrado ou .specify/extensions.yml nã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:

  1. Execute .specify/scripts/bash/check-prerequisites.sh --json --paths-only da raiz do repositório uma vez (modo combinado --json --paths-only / -Json -PathsOnly). Analise os campos mínimos do payload JSON:

    • FEATURE_DIR
    • FEATURE_SPEC
    • (Opcionalmente, capture IMPL_PLAN, TASKS para fluxos encadeados futuros.)
    • Se a análise JSON falhar, aborta e instrua o usuário a executar novamente /speckit-specify ou 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").
  2. SE EXISTIR: Carregue .specify/memory/constitution.md para obter princípios do projeto e restrições de governança.

  3. 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)
  4. 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).
  5. 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.
    • 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çãoDescriçã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)
      PersonalizadoForneç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.
    • 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.

  6. 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 ## Esclarecimentos exista (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-DD para hoje.
    • 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).
  7. 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.
  8. Grave a especificação atualizada de volta em FEATURE_SPEC.

  9. Revalidar a Lista de Verificação de Qualidade da Especificação (se existir):

    • Verifique se FEATURE_DIR/checklists/requirements.md existe.
    • Se NÃO existir, pule esta etapa silenciosamente.
    • Se existir:
      1. Leia o arquivo da lista de verificação.
      2. 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).
      3. 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.
      4. Reavalie cada item da caixa de seleção em relação à especificação atualizada (a versão recém-salva na etapa 7).
      5. 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á.
      6. Registre as alterações reais (se houver) gravando o arquivo atualizado.
      7. 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).

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

Habilidades Relacionadas