alirezarezvani/claude-skills

Dossiê — Pesquisa de Entidades de Nível Decisório

Portabilidade: Requer WebSearch + WebFetch, Node.js com o pacote docx e, opcionalmente, bash_tool + curl para APIs gratuitas (SEC EDGAR, GitHub, ProPublica). MCPs BYOK (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) são melhorias opcionais. Funciona nativamente no Claude Code CLI.

Estrutura Não Genérica — O Diferencial

Esta habilidade é pesquisa de entidades de nível decisório com teste de hipótese. Ela recusa um "me fale sobre a Microsoft". Toda invocação força o usuário a expor sua hipótese antecipadamente (Q4) para que o dossiê a teste em vez de confirmá-la.

O formato de caso de uso:

"Vou apresentar uma proposta para a Microsoft na terça. Minha hipótese é que eles estão consolidando gastos de IA em sua plataforma Foundry própria. Valide ou refute, e me dê três ganchos de conversa ligados ao que você encontrar."

NÃO:

"Me fale sobre a Microsoft."

A pergunta obrigatória Q4 — a hipótese — é a âncora não genérica. Pule-a e a habilidade produz um resumo da Wikipédia.

Consulte references/hypothesis_testing_discipline.md para o cânone.

Regras de Integridade do Agente (Convenção Research-Pack)

Fixadas textualmente conforme auditoria PR #657.

• Disciplina de execução. Chamadas de busca sequenciais. WebSearch + WebFetch têm limites de taxa mais flexíveis que o Consensus, mas ainda aplique etiqueta de 1 consulta/segundo. Confirme o recebimento da resposta antes da próxima chamada.
• Disciplina de fontes. Cite apenas fontes retornadas pelas chamadas de ferramenta desta sessão. Conhecimento da Wikipédia / treinamento rotulado como [Contexto — verifique antes de citar] e excluído da contagem de descobertas principais.
• Rastreamento de três contagens. Consultas enviadas / fontes recebidas / fontes citadas. Além disso, uma divisão por nível (primário / secundário / terciário) exclusiva do dossiê. Exibido no registro de auditoria.
• Política de repetição. Em caso de falha → aguarde 3s → tente novamente uma vez → registre. Após 3 falhas consecutivas: pare, avise o usuário.
• Nível de confiabilidade da fonte. Cada citação etiquetada como primária (oficial, SEC, registros judiciais) / secundária (notícias mainstream, imprensa especializada) / terciária (blogs, fóruns). O DOCX exibe o nível em cada bandeira.

Fase 1: Coleta de Requisitos (6 perguntas forçadas, uma de cada vez)

P1 (raiz) — Identidade do sujeito

Quem é o sujeito? Dê-me o nome exato e, se for uma empresa, o site ou URL do LinkedIn. Se for uma pessoa, a URL do LinkedIn ou um identificador único (afiliação à empresa + cargo).

Por que estou perguntando: Desambiguação. Existem 47 João Silvas. Existem três empresas chamadas "Atlas". Preciso de uma entidade específica para pesquisar.

Se o usuário fornecer apenas um nome, insista por um segundo identificador. Recuse-se a prosseguir com nomes ambíguos.

P2 (depende da P1) — Tipo de sujeito

Que tipo de sujeito é este? Escolha um: pessoa / empresa / organização sem fins lucrativos / órgão governamental / outro.

Por que estou perguntando: Matrizes de fontes diferentes se aplicam. Para pessoas, verifico LinkedIn, GitHub, Acadêmico, notícias; para empresas, verifico SEC EDGAR (se pública), Crunchbase, notícias, GitHub para organizações de tecnologia; para organizações sem fins lucrativos, verifico Formulários 990 no ProPublica.

Escolha forçada. "Outro" requer uma descrição de uma linha.

P3 (depende da P2) — Propósito

Para o que você está se preparando? Escolha um:

1. Reunião de vendas / proposta de parceria
2. Diligência de investimento
3. Diligência de aquisição
4. Jornalismo / diligência devida
5. Preparação para entrevista de emprego
6. Inteligência competitiva
7. Verificação pessoal (encontro, contratação, sócio)
8. Outro (especifique)

Por que estou perguntando: O propósito dita o ângulo, a profundidade e a sensibilidade das bandeiras vermelhas. A preparação para vendas precisa de ganchos de conversa. A diligência de investimento precisa de sinais de tração. A verificação pessoal precisa de limites de sensibilidade cuidadosos.

P4 (depende da P3) — Hipótese — OBRIGATÓRIA

Qual é a sua hipótese inicial? O que você já acredita sobre este sujeito e o que deseja verificar ou refutar?

Por que estou perguntando: Esta é a pergunta crítica. Um dossiê que apenas confirma o que você já pensa é inútil. Ao declarar sua hipótese antecipadamente, posso buscar evidências que a refutariam bem como evidências que a apoiam — e dar a você um veredito que realmente pode usar.

Exemplos:

• "Acredito que a Microsoft está consolidando gastos de IA no Foundry próprio. Verifique ou refute."
• "Acho que o CEO está sobrecarregado — muito papo de TAM, nenhuma tração. Teste isso."
• "Acredito que a taxa de despesas indiretas desta organização sem fins lucrativos é suspeita. Verifique os 990s."
• "Acho que esta pessoa é técnica o suficiente para um cargo de CTO. Verifique."

OBRIGATÓRIA. Se o usuário disser "não tenho uma", insista uma vez: "Então chute. Comprometa-se com uma posição que você possa atualizar depois. O dossiê precisa de uma hipótese para testar; caso contrário, é um perfil genérico e não ajudará você a tomar uma decisão."

Se ainda assim recusar: recorra à hipótese implícita "qual é a coisa mais surpreendente que poderia encontrar?" e sinalize a alternativa no registro de auditoria.

Esta pergunta é a âncora não genérica. Pule-a e a habilidade se torna um resumo da Wikipédia.

P5 (depende da P3) — Profundidade

Horizonte de tempo: resumo de 5 minutos ou dossiê de nível decisório de 15 minutos?

Por que estou perguntando: O modo resumo limita a ~10 buscas e pula as passagens de rede e reputação. O modo decisório vai mais fundo em cada seção. Escolha com base no quanto você está investindo nesta decisão.

Escolha forçada.

P6 (perguntada apenas se P3 ∈ {jornalismo, verificação pessoal}) — Sensibilidades

Algo sensível a excluir? Por exemplo, dados médicos pessoais, detalhes familiares, histórico político ou tópicos específicos proibidos?

Por que estou perguntando: Alguns contextos de pesquisa têm restrições éticas. Prefiro saber antecipadamente do que apresentar algo que você nunca compartilharia.

Pule para vendas/investimento/aquisição/inteligência competitiva (baixa sensibilidade); pergunte para jornalismo/verificação pessoal (alta sensibilidade).

Condição de parada: Após a P6 (ou antes com pulos de dependência), confirme e inicie a Fase 2. Nunca reabra a coleta de requisitos após a Fase 2 começar.

Fase 2: Desambiguação do Sujeito

Antes da Fase 3, resolva o sujeito para uma entidade específica:

• Para pessoas: confirme URL do LinkedIn OU (empregador + cargo + cidade)
• Para empresas: confirme domínio OU (nome legal + jurisdição de incorporação)
• Para organizações sem fins lucrativos: confirme EIN OU (nome legal + estado)
• Para órgãos governamentais: confirme URL oficial .gov

Se ainda ambíguo após a insistência da P1: pare e repita a P1 com identificadores de desambiguação. Recuse-se a prosseguir.

Fase 3: Seleção da Matriz de Fontes

Roteada pelo tipo de sujeito P2. Consulte references/subject_type_source_matrix.md para o cânone completo.

Pessoa

• LinkedIn (busca manual ou MCP do LinkedIn se BYOK)
• Site pessoal
• Twitter/X (limitado por taxa; degrade graciosamente)
• GitHub (se sujeito técnico)
• Google Acadêmico (se acadêmico)
• Notícias (WebSearch + WebFetch)
• Transcrições de palestras, podcasts (WebSearch)

Empresa

• Site oficial (sobre, liderança, notícias, carreiras)
• SEC EDGAR (API gratuita; 10-Ks, 10-Qs, 8-Ks para empresas públicas)
• Camada gratuita do Crunchbase (ou MCP do Crunchbase se BYOK)
• Notícias (WebSearch + WebFetch)
• GitHub (para organizações de tecnologia)
• Glassdoor + Comparably (sentimento; degrade graciosamente se o scraping for bloqueado)
• Página da empresa no LinkedIn

Organização sem fins lucrativos

• ProPublica Nonprofit Explorer (gratuito; Formulários 990)
• Site oficial
• Notícias
• GuideStar (se acessível)

Órgão governamental

• Sites oficiais .gov
• Notícias
• ProPublica (para agências federais)

Se um MCP pago estiver conectado (Apollo, Pitchbook, SimilarWeb), use-o, mas marque as descobertas como originadas de BYOK no registro de auditoria.

Fase 4: Busca Orientada por Hipótese

Toda busca da Fase 4 DEVE ser classificada como:

• Evidência de apoio (confirma a hipótese), OU
• Evidência refutativa (refutaria a hipótese)

≥30% do orçamento de busca alocado para consultas refutativas. Aplicado via scripts/disconfirming_evidence_balance.py.

Exemplo para a hipótese "Microsoft está consolidando gastos de IA no Foundry":

• Apoio: "Adoção do Microsoft Foundry 2026", "Consolidação da infraestrutura de IA da Microsoft"
• Refutativo: "Re negociação do acordo Microsoft OpenAI", "Diversificação de fornecedores de IA da Microsoft", "Parcerias de modelos de terceiros da Microsoft 2026"

Isso é o que torna o dossiê de nível decisório em vez de enviesado por confirmação.

Para cada busca:

• Registre via citation_tracker.py com classificação (apoio / refutativo)
• Aplique o nível de fonte de source_tier_classifier.py a cada URL de resultado

Fase 5: Linha do Tempo de Atividades de 12 Meses

Janela padrão de 12 meses para a linha do tempo de atividades; mais profunda para identidade fundamental.

Categorias:

• Notícias (aquisições, contratações, saídas, lançamentos de produtos)
• Rodadas de financiamento / eventos financeiros
• Controvérsias / eventos legais
• Declarações públicas / mudanças de estratégia

Ordem cronológica reversa. Cada entrada com hiperlink e nível.

Fase 6: Sinais de Rede + Reputação

Rede

• Empresas: investidores (entrada/saída), clientes (nomeados), parceiros
• Pessoas: co-fundadores, conselheiros, mentores, empregadores, cargos em conselhos
• Organizações sem fins lucrativos: financiadores, conselho, liderança

5-10 entradas, classificadas por relevância para a hipótese.

Reputação

• Sentimento de notícias (últimos 12 meses)
• Glassdoor para empresas (classificação geral + 3 avaliações representativas)
• Menções de pares para pessoas
• Advertência: dados de reputação são ruidosos; classifique adequadamente

Fase 7: Passagem de Bandeiras Vermelhas

Apresente, mas não sensacionalize:

• Litígios (registros judiciais → nível primário)
• Ações regulatórias (SEC, DOJ, ações de agências → primário)
• Saídas incomuns (saídas de pessoal-chave em até 90 dias)
• Sinais financeiros (notas de continuidade operacional em 10-Ks → primário)
• Impactos na reputação (cobertura negativa sustentada → secundário)

Cada bandeira com nível. O nível aparece ao lado de cada bandeira no DOCX.

Fase 8: Geração de Ganchos de Conversa

3-5 ganchos específicos vinculados a descobertas reais, não a pontos de discussão genéricos.

Consulte references/conversation_hook_quality.md para o cânone.

❌ Genérico	✅ Vinculado a descoberta
"Pergunte sobre o roteiro deles"	"Mencione a aquisição recente de [X] — isso sinaliza que estão investindo na vertical Y. Sugestão de abordagem: 'Vi o anúncio do [X] — como isso muda seu roteiro em Y?'"
"Pergunte sobre contratações"	"O VP de Engenharia deles saiu há 3 semanas (LinkedIn). Sugestão de abordagem: 'Percebi que [nome] seguiu em frente — qual é o plano de liderança de engenharia?'"
"Fale sobre os valores deles"	"Eles atualizaram a página de preços na semana passada (site oficial). Sugestão de abordagem: 'Vi a atualização de preços — o que motivou isso?'"

Cada gancho:

• O gancho (uma frase)
• A descoberta à qual está vinculado (com hiperlink + nível)
• Sugestão de abordagem (redação textual que o usuário pode adaptar)

Fase 9: Geração do DOCX (9 Seções)

Através de Node.js + biblioteca docx.

1. Resumo Executivo — um parágrafo: quem são + por que são importantes + veredito sobre a hipótese (APOIADA / PARCIALMENTE APOIADA / REFUTADA / INCONCLUSIVA) + 3 marcadores de coisas que você deve saber.
2. Tabela de Fatos de Identidade — fundação/nascimento, localização, tamanho/estágio, cargo atual, afiliações principais. Todas as células com fonte; nível em texto flutuante.
3. Teste de Hipótese — hipótese do usuário declarada textualmente. Evidências de apoio (3-5 marcadores com citações com hiperlink). Evidências refutativas (3-5 marcadores com citações com hiperlink). Parágrafo de veredito (2-3 frases explicando o peso).
4. Linha do Tempo de Atividades de 12 Meses — Notícias, financiamento, contratações, saídas, lançamentos de produtos, controvérsias. Ordem cronológica reversa. Cada entrada com hiperlink.
5. Sinais de Rede — Colaboradores / investidores / associados. 5-10 entradas, classificadas por relevância para a hipótese.
6. Sinais de Reputação — Sentimento de notícias, Glassdoor para empresas, menções de pares para pessoas. Advertência: dados de reputação são ruidosos.
7. Bandeiras Vermelhas + Padrões Ocultos — Litígios, ações regulatórias, saídas incomuns, sinais financeiros, impactos na reputação. Com níveis.
8. Ganchos de Conversa — 3-5 ganchos específicos vinculados a descobertas. Cada um: gancho + descoberta + sugestão de abordagem.
9. Proveniência de Fontes + Registro de Auditoria — Lista por fonte com nível. Tabela de resumo de busca (#, consulta, classificação, fontes retornadas, fontes citadas). Três contagens + contagens por nível. Buscas com falha. Sinalização de uso de MCP BYOK.

Estilização

Corpo Arial 12pt, títulos em azul marinho (#1a3a5c), cabeçalhos de tabela em azul claro (#e8f0f8), destaque de bandeira vermelha em vermelho, destaque de gancho de conversa em verde.

Padrões de hiperlink

new ExternalHyperlink({
  link: "https://...",
  children: [new TextRun({ text: título, style: "Hyperlink" })],
});

Fase 10: Entrega

• Salvar: <output-dir>/dossier_<slug-da-entidade>_<YYYY-MM-DD>.docx
• Resumo no chat: caminho do arquivo + veredito sobre a hipótese + contagens de auditoria + divisão por nível + MCPs BYOK usados (se houver)
• Validar: verifique a integridade do zip com python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx> (sem saída = intacto), depois confirme que as seções necessárias estão presentes

Ferramentas

Script	Função
scripts/citation_tracker.py	Auditoria de três contagens + classificação de apoio/refutação + etiquetagem de nível de fonte em ~/.dossier_sessions/<session>.json
scripts/disconfirming_evidence_balance.py	Verifica se ≥30% do orçamento de busca foi alocado para consultas refutativas; avisa se enviesado
scripts/source_tier_classifier.py	URL → classificação primária / secundária / terciária via heurísticas de domínio

Referências

• references/hypothesis_testing_discipline.md — regra dos ≥30% + nível decisório vs enciclopédico (7+ fontes)
• references/subject_type_source_matrix.md — matrizes de fonte para pessoa/empresa/org.sem fins lucrativos/gov (7+ fontes)
• references/conversation_hook_quality.md — disciplina de gancho vinculado a descoberta (7+ fontes)

Tratamento de Erros

Falha	Comportamento
Nome do sujeito ambíguo	Recuse-se a prosseguir. Repita a P1 com identificador de desambiguação.
Usuário se recusa a declarar hipótese	Insista uma vez. Se ainda recusar, recorra à hipótese implícita "qual é a coisa mais surpreendente que poderia encontrar?". Sinalize na auditoria.
Sujeito não tem pegada pública alguma	Sinalize falha de cobertura no registro. Ainda entregue o dossiê com as seções 1 e 2, mais as seções que puderem ser preenchidas.
API gratuita (SEC/ProPublica/GitHub) sem resposta	Repetição única com backoff de 3s. Se ainda falhar, sinalize como fonte não disponível e prossiga com fontes restantes.
Geração do DOCX falha	Capture a exceção, registre o rastreamento, informe o usuário com o conteúdo de texto bruto como fallback.

Limitações Conhecidas

• Sem capacidade de rastreamento em tempo real. A pesquisa é um instantâneo no momento da execução. Atualize executando novamente o dossiê.
• APIs gratuitas têm limites de taxa. SEC EDGAR tem limites generosos; ProPublica e GitHub podem exigir chaves de API para uso intenso.
• O sentimento do Glassdoor pode estar desatualizado e é notoriamente tendencioso para ex-funcionários insatisfeitos. Classifique evidências do Glassdoor como secundárias/terciárias por padrão.
• A verificação pessoal respeita limites éticos estritos. Nenhuma varredura de deep web, nenhuma tentativa de contornar paywalls, nenhum dado pessoal além do que está publicamente disponível em contextos profissionais/de notícias.

Notas Finais

1. Sempre priorize fontes oficiais (SEC, sites .gov, LinkedIn) em detrimento de secundárias (imprensa, blogs).
2. Se o usuário solicitar um "perfil rápido" (5 min), entregue apenas as seções 1-4 + 9 e pule as passagens de rede/reputação/bandeiras.
3. O arquivo DOCX gerado é autocontido: todos os hiperlinks funcionam, todas as citações são rastreáveis de volta à fonte.
4. O registro de auditoria na seção 9 é a única forma de verificação. Consulte-o primeiro se o usuário questionar a precisão.

---

Dossiê v2.3 — Compatível com Claude Code. Veja README.md para instruções de instalação e configuração.