Communitygithub.com

tangjuyo/reels-blocker

Realiza uma análise de consistência e qualidade não destrutiva entre spec.md, plan.md e tasks.md após a geração de tarefas.

O que é reels-blocker?

Este skill realiza uma análise estruturada e não destrutiva da consistência e qualidade entre três artefatos principais do projeto: spec.md, plan.md e tasks.md. Ele é projetado para ser executado após a conclusão bem-sucedida do comando `/speckit-tasks`, que gera o `tasks.md`. O skill verifica duplicações, ambiguidades, subespecificações, alinhamento com a constituição do projeto (`.specify/memory/constitution.md`), lacunas de cobertura e inconsistências entre os artefatos. Ele suporta hooks de extensão antes e depois da análise, definidos no arquivo `.specify/extensions.yml`, permitindo integração com ferramentas externas. O resultado é um relatório de análise em Markdown com uma tabela de descobertas categorizadas por severidade (CRITICAL, HIGH, MEDIUM, LOW), uma tabela de cobertura de requisitos, métricas e ações recomendadas. O skill é estritamente somente leitura e nunca modifica arquivos; ele oferece uma etapa opcional de remediação onde o usuário pode solicitar sugestões de edição para os principais problemas identificados.

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

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 de Pré-Execução

Verificar hooks de extensão (antes da análise):

  • Verifique se o arquivo .specify/extensions.yml existe 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.yml nã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 é explicitamente false. Trate hooks sem um campo enabled como habilitados por padrão.
  • Para cada hook restante, não tente interpretar ou avaliar expressões de condition do 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 condition não vazia, pule o hook 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 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):
      ## 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.
      
      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 {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.
  • Se nenhum hook estiver registrado ou .specify/extensions.yml nã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.md para 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

IDCategoriaSeveridadeLocal(is)ResumoRecomendação
A1DuplicaçãoALTOspec.md:L120-134Dois 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 RequisitoTem Tarefa?IDs de TarefasNotas

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.yml nã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 é explicitamente false. Trate hooks sem um campo enabled como habilitados por padrão.
  • Para cada hook restante, não tente interpretar ou avaliar expressões de condition do 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 condition não vazia, pule o hook 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 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):
      ## Extension Hooks
      
      **Hook Automático**: {extensão}
      Executando: `/{comando}`
      EXECUTE_COMMAND: {comando}
      
      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 {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.
  • Se nenhum hook estiver registrado ou .specify/extensions.yml nã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

Individual skills in this repo

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

Habilidades Relacionadas