Communitygithub.com

tangjuyo/bloqueador-de-reels

Avalia a base de código atual contra a especificação, plano e tarefas de uma funcionalidade, e anexa qualquer trabalho não concluído como novas tarefas no tasks.md para que o implementador possa finalizá-lo.

O que é bloqueador-de-reels?

Esta habilidade do Claude Code, chamada 'reels-blocker' (ou 'bloqueador de reels'), é uma ferramenta de convergência que garante que o código implementado esteja alinhado com a especificação, plano e tarefas definidas para uma funcionalidade. Ela funciona lendo os arquivos spec.md, plan.md e tasks.md, analisando o estado atual do código e identificando lacunas (requisitos não atendidos, implementações parciais ou contraditórias). Para cada lacuna encontrada, a habilidade anexa novas tarefas ao final do tasks.md em uma nova seção 'Phase N: Convergence', sem modificar tarefas existentes ou o código da aplicação. É útil para desenvolvedores que usam um fluxo de trabalho estruturado com especificação, planejamento e tarefas (como no Speckit), garantindo que nenhum requisito seja esquecido durante a implementação. A habilidade também suporta hooks de extensão (before/after converge) e respeita uma constituição do projeto (constitution.md) como guia de princípios não negociáveis.

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

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 hooks de extensão (antes da convergência):

  • Verifique se .specify/extensions.yml existe na raiz do projeto.

  • Se existir, leia-o e procure por entradas na chave hooks.before_converge.

  • Se o YAML não puder ser analisado ou for inválido, não ignore silenciosamente: avise o usuário que .specify/extensions.yml não pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados ali, depois continue normalmente.

  • Filtre os hooks onde enabled está explicitamente como false. Trate hooks sem um campo enabled como habilitados por padrão.

  • Para cada hook restante, não tente interpretar ou avaliar expressões condition dos hooks:

    • 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 de hooks, substitua pontos (.) por hífens (-). Por exemplo, speckit.git.commit → /speckit-git-commit.

  • Para cada hook executável, produza a seguinte saída com base em sua flag optional:

    • Hook opcional (optional: true):

      ## Hooks de Extensão
      
      **Pré-Hook Opcional**: {extension}
      Comando: `/{command}`
      Descrição: {description}
      
      Prompt: {prompt}
      Para executar: `/{command}`
      
    • Hook obrigatório (optional: false):

      ## Hooks de Extensão
      
      **Pré-Hook Automático**: {extension}
      Executando: `/{command}`
      EXECUTE_COMMAND: {command}
      
      Aguarde o resultado do comando do hook antes de prosseguir para o Objetivo.
      

      Após emitir o bloco acima, você DEVE de fato 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 ID literal {command} mostrado acima; por exemplo, um agente em modo de habilidades 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

Eliminar a lacuna entre o que a especificação, plano e tarefas de uma funcionalidade exigem e o que a base de código atualmente implementa. Leia spec.md, plan.md e tasks.md como a única fonte de intenção (com a constituição como restrições governantes), avalie o estado atual do código, determine quais requisitos, critérios de aceitação, decisões de plano e tarefas existentes estão não atendidos, incompletos ou apenas parcialmente satisfeitos, e anexe cada parte do trabalho restante como uma nova tarefa rastreável no final de tasks.md para que /speckit-implement possa concluí-la. Este comando DEVE ser executado somente após /speckit-implement ter sido executado no tasks.md atual, e após /speckit-tasks ter produzido um tasks.md completo.

Isso não é uma ferramenta de diff e não rastreia alterações. Ela avalia o estado atual do código em relação aos artefatos da funcionalidade — sem git, sem comparação de branches, sem histórico.

Restrições Operacionais

SOMENTE ANEXAR, NUNCA REESCREVER: A única gravação do comando é anexar uma nova seção ## Phase N: Convergence ao tasks.md. O comando NÃO DEVE:

  • modificar spec.md ou plan.md de forma alguma;
  • reescrever, renumerar, reordenar ou excluir qualquer tarefa existente (incluindo tarefas de uma fase de Convergência anterior);
  • modificar, criar ou excluir qualquer código de aplicação — completar as tarefas anexadas é trabalho do /speckit-implement.

Quando a base de código já satisfizer tudo, o comando DEVE deixar tasks.md byte por byte inalterado (nenhum cabeçalho de Convergência vazio) e relatar um resultado limpo.

Autoridade da Constituição: A constituição do projeto (.specify/memory/constitution.md) é innegociável. Código que viola um princípio MUST é a descoberta de maior gravidade e produz uma tarefa de remediação correspondente. Se a constituição for um modelo não preenchido, pule as verificações da constituição de forma elegante, sem falhar.

Etapas de Execução

1. Inicializar o Contexto de Convergência

Execute .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks uma vez 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
  • CONSTITUTION = .specify/memory/constitution.md (se presente)

Se spec.md, plan.md ou tasks.md estiver faltando, PARE com uma mensagem clara e acionável nomeando o comando pré-requisito a ser executado (/speckit-specify para especificação faltante, /speckit-plan para plano faltante, /speckit-tasks para tarefas faltantes). Não produza saída parcial.

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:

De spec.md:

  • Requisitos Funcionais (FR-###)
  • Critérios de Sucesso (SC-###) — inclua apenas itens que exigem trabalho construtível; exclua métricas de resultado pós-lançamento e KPIs de negócio
  • Histórias de Usuário e seus Cenários de Aceitação
  • Casos de Borda (se presentes)

De plan.md:

  • Escolhas de arquitetura/stack e decisões técnicas
  • Referências ao Modelo de Dados
  • Fases e pontos de contato nomeados (arquivos/componentes que o plano diz que serão criados ou editados)
  • Restrições técnicas

De tasks.md:

  • IDs de Tarefas (para calcular o próximo ID e o próximo número de fase)
  • Descrições, agrupamento de fases e caminhos de arquivos referenciados

Da constituição (se não for um modelo não preenchido):

  • Nomes de princípios e declarações normativas MUST/SHOULD

3. Construir o Inventário de Intenções

Crie um modelo interno (não ecoe artefatos brutos):

  • Inventário de requisitos: uma chave estável por FR-### / SC-### / cenário de aceitação de história de usuário (por exemplo, US1/AC2), mais as decisões de plano e princípios constitucionais que impõem obrigações construtíveis.
  • Mapa de escopo de código: a partir dos caminhos de arquivo nomeados em plan.md e tasks.md, mais uma pesquisa por palavra-chave para os conceitos que cada requisito descreve, derive o conjunto de arquivos fonte e componentes no escopo para avaliação. Limite a avaliação a estes — não infira escopo além do que os artefatos definem.

4. Avaliar a Base de Código e Classificar Descobertas

Inclua cada tarefa existente no inventário de intenções, independentemente do estado da caixa de seleção ou da fase de Convergência: alegações de conclusão não são evidência. Verifique o comportamento atual em relação à especificação, plano, tarefas e constituição; para cadeias de tarefas corretivas, avalie o comportamento resultante, não detalhes de implementação substituídos. Verifique tanto obrigações não atendidas quanto implementação que contradiz, excede ou está fora da intenção declarada.

Para cada item no inventário de intenções, inspecione o código atual no escopo e produza uma Finding somente onde houver uma lacuna. Classifique cada descoberta por tipo de lacuna:

  • missing: o trabalho necessário está ausente do código completamente.
  • partial: o trabalho existe mas ainda não satisfaz completamente o requisito / critério de aceitação / decisão de plano.
  • contradicts: o código faz algo que conflita com a intenção declarada ou um princípio MUST da constituição.
  • unrequested: o código contém trabalho não solicitado pela especificação, plano ou tarefas (apresentado para conscientização — convergir não exclui código, apenas anexa uma tarefa para revisar/justificar ou remover).

Cada Finding registra: um id estável, a source-ref à qual remete, o gap-type, uma severidade e uma descrição curta legível com a evidência (o arquivo/área observado).

Casos de borda:

  • Pouco ou nenhum código ainda: trate todo o escopo especificado como trabalho missing restante, em vez de falhar.
  • Nada resta: produza zero descobertas e siga o ramo convergido na Etapa 7.

5. Atribuir Severidade

  • CRITICAL: viola um princípio MUST da constituição, ou uma lacuna missing/contradicts que bloqueia a funcionalidade básica de uma história de usuário P1.
  • HIGH: uma lacuna missing ou partial em um requisito funcional principal ou critério de aceitação.
  • MEDIUM: uma lacuna partial em um requisito secundário, ou uma adição unrequested com justificativa pouco clara.
  • LOW: lacunas parciais menores, polimento ou adições unrequested de baixo risco.

6. Apresentar o Resumo das Descobertas na Sessão

Antes de anexar qualquer coisa, produza um resumo compacto, graduado por severidade (ainda sem gravações de arquivo):

Descobertas de Convergência

IDTipo de LacunaSeveridadeFonteEvidênciaTrabalho Restante
F1missingHIGHFR-008Exemplo: nenhuma proteção append-only detectada em caminho/para/modulo.py ao escrever tasks.mdAdicionar aplicação de append-only

Métricas de resumo:

  • Requisitos / critérios de aceitação verificados
  • Decisões de plano verificadas
  • Princípios constitucionais verificados (ou "ignorado — modelo")
  • Descobertas por tipo de lacuna (missing / partial / contradicts / unrequested)
  • Descobertas por severidade

7. Anexar Tarefas de Convergência (ou relatar convergido)

Se houver uma ou mais descobertas acionáveis (resultado tasks_appended):

Anexe ao final de tasks.md, conforme o contrato de anexação:

  1. Escaneie todos os IDs de tarefas existentes; seja M o máximo. Determine o próximo número de fase N (fase existente mais alta + 1).

  2. Escreva um único cabeçalho de nova seção ## Phase N: Convergence.

  3. Emita um item de lista de verificação por descoberta acionável, ordenado por CRITICAL/HIGH primeiro, atribuindo IDs preenchidos com zero T{M+1:03d}, T{M+2:03d}, …:

    - [ ] T042 <descrição imperativa> por <source-ref> (<gap-type>)
    

    <source-ref> rastreia a tarefa até sua origem: por exemplo, FR-003, SC-002, US1/AC2, plan: decisão de armazenamento, Constitution II.

    <gap-type> é um de missing, partial, contradicts, unrequested.

    Tarefas de violação da constituição DEVEM ser emitidas primeiro e descritas como CRITICAL.

  4. Nunca reutilize ou renumerie IDs existentes. Se uma fase de Convergência anterior existir, adicione uma nova, numerada separadamente, abaixo dela — não toque na antiga.

Se não houver descobertas acionáveis (resultado converged):

  • Não modifique tasks.md de forma alguma — nenhum cabeçalho de fase vazio.
  • Relate: "✅ Convergido — a implementação satisfaz a especificação, o plano e as tarefas."
  • Inclua as contagens de resumo do que foi verificado.

8. Fornecer Próximas Ações (Handoff)

  • Em tasks_appended: informe quantas tarefas foram anexadas e sob qual fase, e recomende executar /speckit-implement para completá-las; observe que uma execução de convergência subsequente encontrará menos ou nenhum item restante.
  • Em converged: recomende prosseguir para revisão / abrir um PR. Nenhuma passada de implementação adicional é necessária para o escopo especificado desta funcionalidade.

9. Verificar hooks de extensão

Após produzir o resultado, verifique se .specify/extensions.yml existe na raiz do projeto.

  • Se existir, leia-o e procure por entradas na chave hooks.after_converge.

  • Se o YAML não puder ser analisado ou for inválido, não ignore silenciosamente: avise o usuário que .specify/extensions.yml não pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados ali, depois continue normalmente.

  • Filtre os hooks onde enabled está explicitamente como false. Trate hooks sem um campo enabled como habilitados por padrão.

  • Para cada hook restante, não tente interpretar ou avaliar expressões condition dos hooks:

    • 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.
  • Relate o resultado da convergência (converged ou tasks_appended) na sessão antes de listar quaisquer hooks, para que os usuários possam decidir se devem executar comandos de acompanhamento opcionais.

  • Ao construir invocações de comando a partir de nomes de comando de hooks, substitua pontos (.) por hífens (-). Por exemplo, speckit.git.commit → /speckit-git-commit.

  • Para cada hook executável, produza a seguinte saída com base em sua flag optional:

    • Hook opcional (optional: true):

      ## Hooks de Extensão
      
      **Hook Opcional**: {extension}
      Comando: `/{command}`
      Descrição: {description}
      
      Prompt: {prompt}
      Para executar: `/{command}`
      
    • Hook obrigatório (optional: false):

      ## Hooks de Extensão
      
      **Hook Automático**: {extension}
      Executando: `/{command}`
      EXECUTE_COMMAND: {command}
      

      Após emitir o bloco acima, você DEVE de fato 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 ID literal {command} mostrado acima; por exemplo, um agente em modo de habilidades 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.

Individual skills in this repo

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

Habilidades Relacionadas