CommunityEscrita e Ediçãogithub.com

MJL-ren/blindspot-audit

Uma habilidade portátil para agentes de IA que encontra pontos cegos, riscos ocultos e decisões ausentes em projetos, com um registro durável para auditorias repetidas em Claude Code, Codex e OpenCode.

O que é blindspot-audit?

O Blindspot Audit é uma habilidade especializada para agentes de IA como Claude Code, Codex e OpenCode, projetada para descobrir lacunas entre o entendimento do usuário sobre um projeto e a realidade do projeto. Em vez de apenas verificar listas genéricas de qualidade, esta habilidade aplica sistematicamente estruturas externas para identificar 'desconhecidos desconhecidos' — conceitos, riscos ou decisões ausentes que o usuário nunca considerou. Ela opera classificando descobertas em quatro categorias (conhecidos conhecidos, conhecidos desconhecidos, desconhecidos conhecidos e desconhecidos desconhecidos) e usando modos como quick, deep, interview e planning para se adaptar a diferentes situações. A auditoria se integra com um registro durável (BLINDSPOT_LEDGER.md) para rastrear descobertas ao longo do tempo, evitando repetições e garantindo progresso em auditorias subsequentes. Uma característica chave é sua 'varredura externa de olhos frescos', que verifica mudanças no mundo real (como regulamentações ou políticas de plataforma) que o repositório do projeto não poderia conter, tornando-a especialmente valiosa para projetos em evolução rápida onde o conhecimento do proprietário está desatualizado.

Funciona com✓Claude Code✓Codex CLI~Cursor✓OpenCode
npx skills add MJL-ren/blindspot-audit

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

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

Documentação

Auditoria de Pontos Cegos

Propósito

Encontrar a lacuna entre o mapa que o usuário tem de um projeto e o território real do projeto. Transformar desconhecidos desconhecidos em desconhecidos conhecidos concretos que o usuário possa inspecionar, responder, testar ou adiar intencionalmente.

O contexto de um projeto é autosselecionado: o proprietário só pode escrever o que já sabe, então cada README, TODO e plano codifica o mapa que ele carrega em sua cabeça — e uma IA trabalhando com esses arquivos herda os mesmos pontos cegos. Esta auditoria deliberadamente importa referenciais de FORA do projeto para medir essa lacuna.

Esta habilidade não é uma lista de verificação genérica de qualidade. Ela deve identificar o que é excepcionalmente importante para este projeto específico, neste estágio específico, com evidências do repositório ou artefatos fornecidos. A auditoria é bem-sucedida quando o proprietário diz "Eu nem sabia que deveria estar pensando nisso" pelo menos uma vez — E se sente mais calmo depois, porque agora também sabe o que pode ignorar com segurança.

Modelo Central

Classifique as descobertas com a estrutura dos quatro desconhecidos:

  • Conhecidos conhecidos: o que o prompt, a documentação, o código ou os planos já afirmam.
  • Conhecidos desconhecidos: perguntas em aberto já visíveis em documentos, TODOs, planos, comentários ou redação do usuário.
  • Desconhecidos conhecidos: coisas que o usuário reconheceria se mostradas, mas que ainda não verbalizou ou escreveu.
  • Desconhecidos desconhecidos: conceitos ausentes, restrições ocultas ou perguntas não feitas que a forma do projeto implica.

A estrutura importa porque a prescrição difere: um desconhecido conhecido precisa de uma linha de checklist, não de uma palestra; um desconhecido desconhecido precisa de uma breve explicação e do passo mais barato. Uma boa saída não reivindica certeza. Ela expõe candidatos e fornece a próxima verificação mais barata.

Regras Básicas

Elas existem porque o modo de falha desta habilidade não é "perder uma lacuna" — é se tornar um incômodo de lista de verificação genérica que é ignorado.

  1. Os próprios documentos de rastreamento do projeto são um filtro, não uma fonte de descobertas. Qualquer coisa já no README / TODO / roadmap / checklist / lista de issues é um CONHECIDO DESCONHECIDO. Nunca o reporte como uma descoberta. (Dados de campo: este filtro normalmente reduz a lista de candidatos em mais da metade e é o principal motivo pelo qual os proprietários confiam no relatório.)
  2. Limite as principais descobertas a 3-7, classificadas por impacto x probabilidade de o proprietário estar verdadeiramente inconsciente. O excesso vai para uma curta "Lista de observação de baixo sinal" ou para o registro — nunca para a lista principal.
  3. Ausência por si só não é uma descoberta. "Você não tem X" só conta se você puder afirmar a consequência concreta para ESTE projeto e o passo mais barato para fechá-lo.
  4. Sempre inclua as duas seções de confiança: "Verificado e bem coberto" e "Ignorável por agora" (cada ignorado com um gatilho explícito de re-verificação). Elas previnem ansiedade e reexames, e são como o proprietário aprende que o relatório pode ser confiável.
  5. Atenha-se a domínios regulamentados. Para descobertas legais, fiscais ou regulatórias, declare o que você encontrou e sua fonte, depois diga claramente que um profissional deve confirmar. Você é um batedor, não um advogado ou contador.

Modos

  • quick: leia documentos e inventário do projeto, retorne os principais pontos cegos.
  • deep: inspecione caminhos de código, testes, configurações e documentos representativos antes de classificar as descobertas.
  • interview: faça uma pergunta de cada vez quando a resposta mudar arquitetura, fluxo de trabalho, escopo ou risco.
  • post-implementation: compare uma alteração concluída, notas, diffs e testes para encontrar desconhecidos restantes.
  • planning: antes da implementação, levante decisões que provavelmente mudarão modelos de dados, interfaces, fluxos de UX, operações ou verificação.

Inferir o modo a partir da redação do usuário. Se o usuário pedir para executar agora, não faça perguntas sobre modo a menos que o limite da auditoria seja impossível de inferir.

Início Rápido

  1. Identifique a raiz do projeto e o limite da auditoria.
  2. Execute o auxiliar de inventário quando um projeto de sistema de arquivos estiver disponível. O script reside na própria pasta desta habilidade — resolva-o em relação a este SKILL.md:
python <caminho-desta-skill>/scripts/project_inventory.py <raiz-do-projeto> --format md

Use --include-generated apenas quando saídas de tempo de execução, relatórios gerados, logs ou artefatos em cache fazem parte da questão da auditoria.

  1. Leia apenas as referências relevantes:
    • references/archetypes.md: escolha o tipo de projeto e pontos cegos esperados.
    • references/lenses.md: derive e aplique lentes de auditoria.
    • references/host-surfaces.md: adapte perguntas e saídas para Claude Code, Codex, OpenCode, CLI ou superfícies apenas de chat.
    • references/ledger-lifecycle.md: descubra, crie, encaminhe ou atualize um registro durável de pontos cegos.
    • references/report-template.md: formate o resultado.
  2. Descubra ou inicialize o registro de pontos cegos:
    • Se um registro anterior existir, leia-o antes de pesquisar (as regras de execução diferencial se aplicam — veja Registro E Execuções Diferenciais).
    • Se nenhum registro existir e o host puder escrever arquivos, crie BLINDSPOT_LEDGER.md no melhor local de documentação local do projeto, a menos que o usuário tenha solicitado saída somente leitura/chat.
    • Se nenhum registro existir e o host não puder escrever arquivos, inclua o caminho proposto e a primeira entrada do registro no relatório.
  3. Inspecione os arquivos de evidência mais fortes do inventário: README/AGENTS, planos, configurações de pacotes, pontos de entrada do aplicativo, configurações de teste, CI, exemplos de env, esquemas, prompts, arquivos de agente/habilidade e documentos de tempo de execução.
  4. Execute a varredura externa de olhos frescos (veja Fluxo de Trabalho passo 5) quando o host tiver acesso à web.
  5. Classifique as descobertas, entreviste o proprietário onde possível, produza o relatório e atualize o registro.

Política de Superfície do Host

O núcleo da auditoria deve funcionar da mesma forma em Claude Code, Codex, OpenCode, CLI e chat simples. Apenas o estilo de interação muda. Veja references/host-surfaces.md para detalhes por host.

  • Hosts com capacidade de escolha (Claude Code AskUserQuestion, OpenCode question): quando uma decisão muda arquitetura, fluxo de trabalho, escopo ou risco — e para a entrevista de conscientização do proprietário — faça uma pergunta curta de 2-3 opções e registre a opção selecionada no relatório ou registro.
  • Hosts Codex ou apenas chat: não bloqueie em perguntas não críticas. Continue com a suposição reversível mais segura, marque-a como suposição e inclua um Pacote de decisão com as opções que o usuário deve escolher mais tarde.
  • Hosts sem acesso à web: pule a varredura externa de olhos frescos, diga isso explicitamente no relatório e sinalize domínios sensíveis ao tempo (regulamentação, política de plataforma, preços) como não verificados, em vez de afirmá-los a partir do conhecimento de treinamento.
  • Hosts que escrevem arquivos: para auditorias de projeto, crie ou atualize um registro por padrão, a menos que o usuário tenha solicitado saída somente leitura/chat. Mencione o caminho e a edição de roteamento no relatório.
  • Hosts somente leitura ou de compartilhamento público: retorne um relatório portátil com comandos/verificações que o usuário possa executar.

Pergunte imediatamente apenas quando continuar seria arriscado, destrutivo, caro ou provável de produzir resultados enganosos.

Registro E Execuções Diferenciais

Primeira execução:

  1. Escolha o melhor local durável para BLINDSPOT_LEDGER.md usando references/ledger-lifecycle.md.
  2. Crie o registro a partir de templates/BLINDSPOT_LEDGER.md quando gravações de arquivos forem apropriadas.
  3. Adicione o registro à superfície de roteamento mais próxima, como um README de operações, índice de documentação ou ponteiro de handoff, quando esse arquivo de roteamento já existir.
  4. Registre o escopo da auditoria, modo, limites de evidência e primeiras descobertas.

Quando um projeto já possui um registro de pontos cegos:

  1. Trate o registro como uma entrada, não como verdade. Re-verifique descobertas de alto impacto ou desatualizadas em relação ao código/documentação atual.
  2. Classifique a saída como nova, alterada, confirmada, rebaixada, resolvida ou precisa-de-decisão.
  3. Não repita itens pendentes inalterados, a menos que bloqueiem o objetivo atual. Isso é o que faz as execuções repetidas parecerem progresso em vez de incômodo.
  4. Se o registro for novo, mas não roteado por um índice, handoff ou README de operações, sinalize isso como um ponto cego de descoberta.
  5. Preserve o idioma de status local e os IDs do registro ao atualizá-lo.

Registros bons tornam as auditorias futuras mais baratas. Registros ruins se tornam outro documento oculto, então sempre verifique a descoberta.

Higiene de Busca

Use buscas delimitadas. Auditorias de pontos cegos frequentemente tocam repositórios amplos, e arquivos gerados barulhentos podem criar falsa confiança ou desperdiçar contexto.

Exclusões padrão para rg e ferramentas similares, a menos que a auditoria vise explicitamente essas áreas:

!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**

Prefira caminhos direcionados e exclusões --glob em vez de varreduras em todo o repositório. Se uma varredura ampla retornar arquivos gerados enormes, pare e execute novamente com um limite mais restrito antes de usar o resultado.

Fluxo de Trabalho

1. Definir O Mapa

Declare o objetivo aparente do usuário, tipo de projeto, maturidade e seu limite de auditoria em 2-4 linhas. Marque suposições explicitamente. Inclua um perfil do proprietário:

  • Solo ou equipe? Em que o proprietário é claramente especialista e — mais útil — NÃO é especialista? Os pontos cegos se agrupam nas áreas não especializadas do proprietário, então pondere essas lentes para cima.
  • Hobby ou comercial? Privado ou público? Intenção comercial ou pública ativa lentes legais, fiscais e de mercado que seriam puro ruído para um projeto de hobby privado. Se a intenção não for legível a partir dos arquivos, pergunte antes de escanear (uma pergunta curta) — adivinhar errado sobre intenção desperdiça toda a auditoria.

2. Coletar Evidências

Use o auxiliar de inventário mais leituras direcionadas. Leia primeiro as superfícies de autoconsciência do projeto (README, TODO, roadmap, checklists, documentos de design, sinopse/esboço) — elas são tanto sua melhor fonte de perfil quanto seu filtro de ruído (Regra Básica 1). Prefira evidências a especulações amplas. Marque evidências como:

  • observado: diretamente presente em arquivos ou saídas.
  • ausente: artefato esperado não encontrado no escopo inspecionado.
  • inferido: provável a partir de estrutura, nomenclatura ou convenções.
  • pergunta: requer confirmação do usuário ou do proprietário do domínio.

3. Classificar O Território

Escolha um ou mais arquétipos de references/archetypes.md. Não force o projeto em uma categoria se for híbrido.

4. Executar Lentes

Aplique apenas lentes que se ajustem ao estágio do projeto. Um protótipo não precisa de conformidade empresarial, mas ainda pode precisar de limites de perda de dados, tratamento de segredos ou recuperabilidade.

5. Varredura Externa de Olhos Frescos

Quando o host tiver acesso à web, faça pesquisa com tempo limitado sobre duas perguntas:

  1. O que projetos saudáveis desta categoria tratam como equipamento padrão agora?
  2. O que mudou nos últimos 6-12 meses — regulamentação, política de plataforma, mercado ou convenções de gênero, ferramentas — que os documentos deste projeto não poderiam conter?

A pergunta 2 é desproporcionalmente valiosa: mudanças dependentes do tempo são estruturalmente invisíveis tanto para o repositório quanto para a memória do proprietário. (Dados de campo: nas primeiras execuções, as descobertas de maior impacto — uma lei de rotulagem de conteúdo de IA entrando em vigor no mês seguinte, uma aquisição de provedor de pagamento que invalidou um plano documentado — todas vieram desta etapa.) Cite fontes para qualquer coisa encontrada aqui. Sem acesso à web, pule e divulgue (veja Política de Superfície do Host).

6. Converter Pontos Cegos Em Verificações

Para cada descoberta, inclua:

  • o que pode estar faltando.
  • por que é importante para este projeto.
  • evidência.
  • próxima verificação mais barata.
  • provável proprietário ou superfície de decisão.
  • prioridade: agora, próximo, depois ou observar.
  • confiança: alta, média, baixa.

Descarte candidatos que aparecem nos próprios documentos de rastreamento do projeto (Regra Básica 1), mantenha os 3-7 principais e mova o restante para a lista de observação ou registro.

7. Entrevistar O Proprietário

Apresente as descobertas, depois pergunte quais o proprietário já conhecia (uma única pergunta de múltipla escolha funciona bem em hosts com capacidade de escolha). Classifique cada descoberta:

ConscientizaçãoSignificadoPrescrição
desconhecido_desconhecidoO proprietário não sabiaExplique por que é importante aqui + passo mais barato
desconhecido_conhecidoO proprietário sabia, mas não está escrito em lugar nenhumA correção é documentação, não implementação — coloque nos documentos de rastreamento para que agentes e sessões futuras possam ver
pulo_deliberadoO proprietário considerou e escolheu não fazerMova para a lista de pulos COM o motivo e um gatilho de re-verificação

(Dados de campo: nas primeiras execuções, cerca de metade das principais descobertas acabaram sendo desconhecido_conhecido — lacunas reais no repositório, mas não na cabeça do proprietário. A distinção muda completamente o acompanhamento.)

Em hosts que não podem perguntar, marque cada valor de conscientização como não_confirmado, incorpore as perguntas da entrevista no relatório e coloque decisões em aberto em um Pacote de decisão.

8. Manter A Saída Útil

Lidere com os pontos cegos de maior sinal. Sempre inclua as duas seções de confiança (Regra Básica 4). Escreva o relatório e a prosa do registro no idioma que o proprietário está usando na conversa; mantenha IDs, status e valores de conscientização em inglês para que reexecuções permaneçam comparáveis entre sessões e idiomas. Formate conforme references/report-template.md.

Salvaguardas

  • Não apresente melhores práticas genéricas como descobertas, a menos que a evidência do projeto as torne relevantes.
  • Não re-reporte itens que já existem no registro ou nos próprios documentos de rastreamento do projeto.
  • Não exija processo pesado para experimentos pessoais ou protótipos iniciais.
  • Não faça alterações de código a menos que o usuário solicite explicitamente correção.
  • Não afirme que algo está quebrado apenas porque um arquivo está ausente; diga o que a ausência sugere e como confirmar.
  • Trate CI, testes, documentos de lançamento ou arquivos de implantação ausentes como um ponto cego apenas quando o projeto reivindica entrega repetível, handoff compartilhado ou confiabilidade semelhante à produção. Notas pessoais e protótipos iniciais podem não precisar deles.
  • Não enterre o usuário em todos os riscos possíveis. Classifique por adequação ao projeto, raio de explosão, reversibilidade e probabilidade.
  • Quando o usuário não for especialista no domínio, inclua pequenas notas de ensino para pontos cegos desconhecidos.
  • Quando uma descoberta depender do comportamento atual da plataforma externa, verifique com documentos oficiais ou pesquisa atual antes de tratá-la como fato; sem acesso à web, apresente-a como uma suposição com uma instrução de verificação.

Configuração

Nenhuma configuração especial necessária. Os scripts de referência e template são incluídos com a habilidade. Siga o Início Rápido.

Habilidades Relacionadas