swyxio/skills

Resolução Inteligente de Entidades

Resolva identidades no menor nível de esforço que estabeleça uma resposta confiável. Escalone apenas quando identificadores, mapeamentos ou evidências corroborantes existentes forem insuficientes. Este skill se aplica a registros genuinamente ambíguos de pessoas e organizações, incluindo perfis concorrentes ou candidatos de mídia; tarefas comuns de manipulação de imagens e joins determinísticos de ID não o requerem.

Princípio Central

Trate a resolução de entidades como uma investigação em estágios, não como uma simples consulta. Busca exata, slug lookup, popularidade e julgamento de LLM são todos sinais úteis, mas nenhum deve dominar silenciosamente os outros.

Separe três questões:

• Cobertura: enumeramos todas as entidades solicitadas?
• Identidade: este candidato representa a pessoa ou organização solicitada?
• Utilidade: este é o melhor registro utilizável para a tarefa?

Um registro de alta utilidade com evidência de identidade fraca é um risco de falso positivo. Identidade supera popularidade, completude do perfil, disponibilidade de imagem e classificação de busca.

Níveis de Resolução

Escolha o nível suficiente mais baixo; um nível mais alto não é um pré-requisito obrigatório.

• Nível 0 — Identificação direta: Corresponda a um ID estável autoritário, URL canônico ou identificador de conta verificado. Pare quando isso resolver a tarefa.
• Nível 1 — Reconciliação determinística: Use crosswalks explícitos, aliases revisados, IDs específicos de fonte documentados ou links de identidade verificados. Nunca invente um mapeamento.
• Nível 2 — Identificação contextual: Corrobore um nome usando evento, sessão, afiliação adequada ao tempo, perfil pessoal, propriedade de projeto ou identificadores de fonte verificados de forma independente. Escalone quando candidatos ou evidências entrarem em conflito.
• Nível 3A — Descoberta de perfil oficial: Encontre sites e contas sociais auto-controlados, páginas oficiais de palestrantes, diretórios de empregadores ou perfis de projeto e autor. Prefira perfis vinculados a partir de outra fonte confiável.
• Nível 3B — Corroboração independente: Compare identificadores, aliases, eventos, projetos, afiliações e datas em fontes independentes. Cópias sindicalizadas de uma única biografia não contam como confirmação separada.
• Nível 3C — Reconciliação de alias e histórico: Resolva nomes artísticos, variantes ortográficas, transliterações, empregadores históricos, aquisições e aparições em múltiplos eventos usando mapeamentos explícitos ou corroboração independente. Mantenha as afiliações com escopo temporal.
• Nível 3D — Recuperação de candidatos: Pesquise aliases e nomes contextualizados, sonde IDs diretos, URLs e slugs, e use um LLM para sugerir sondas de recuperação direcionadas apenas quando a consulta comum não encontrar registros plausíveis. Candidatos gerados não são identidades verificadas.
• Nível 3E — Adjudicação de alta fidelidade: Compare evidências de identidade, autoridade da fonte, consistência histórica, registros conflitantes e alternativas significativas. Um LLM pode resumir ou reclassificar candidatos, mas não pode substituir a identificação baseada em fontes.
• Nível 4 — Sensível ou não resolvido: Exija revisão explícita quando as identidades permanecerem ambíguas, fusões duradouras ou publicações tiverem consequências significativas, informações privadas seriam expostas ou a identificação biométrica seria necessária. Retorne ambiguous, needs_review ou unresolved.

Fontes Preferidas

Para identidade e auto-apresentação atual, priorize fontes auto-controladas:

1. Website pessoal, blog ou domínio pessoal verificado.
2. Conta X/Twitter.
3. Perfil do LinkedIn.
4. Perfil do GitHub.
5. Perfil do Hugging Face.
6. Google Scholar, Semantic Scholar, ORCID ou perfil de autor do arXiv.
7. Canal pessoal do YouTube.
8. Perfil do Substack, Medium ou Dev.to.
9. Conta Bluesky ou Mastodon.

Links recíprocos, handles consistentes, domínios compartilhados, propriedade de projeto e histórico de publicação fortalecem a identidade. Um nome de exibição correspondente ou selo de plataforma sozinho não estabelece a propriedade da conta.

Altere a prioridade da fonte quando a pergunta mudar:

• Participação em eventos e afiliação histórica: IDs emitidos pelo organizador, páginas oficiais de palestrantes e cronogramas, biografias específicas do evento, registros do Sessionize ou Accelevents e materiais de apresentação contemporâneos superam perfis posteriores.
• Função atual ou auto-apresentação: Um site pessoal mantido recentemente, conta social verificada ou página de empregador atual superam uma biografia antiga de conferência.
• Foto de perfil canônica: Prefira a imagem de perfil auto-selecionada e verificada da pessoa, uma foto oficial aprovada pelo organizador ou um retrato oficial de evento vinculado a um ID estável. Uma URL pública não concede direitos de redistribuição ou treinamento de imagem.
• Busca geral: Use resultados da web para descobrir candidatos ou corroborar fatos; não trate a classificação de busca como prova.

Nunca trate uma miniatura adivinhada, fotografia de sessão próxima, similaridade facial ou incorporação biométrica como evidência de identidade verificada.

Fluxo de Trabalho

1. Classifique a consulta antes de pesquisar. Detecte se é uma entidade única, uma lista de entidades ou uma consulta de grupo difusa (elenco/membro/equipe/org). Termos como members, cast, lineup, team, company, subsidiaries e leadership geralmente significam que uma expansão é necessária.

2. Analise consultas do tipo instrução antes da consulta. Os usuários frequentemente envolvem dicas de entidade em texto de tarefa, como find the full profiles for..., guess the grouping that includes... ou resolve these partial names.... Extraia a região de dica de entidade, preserve a instrução original como contexto e não envie a string de instrução inteira como uma consulta literal ao banco de dados.

3. Expanda consultas difusas em grupos de entidades apenas quando a identificação direta ou mapeamentos documentados forem insuficientes. Use um LLM ou ferramentas de busca quando for genuinamente necessário enumerar indivíduos ou organizações. Mantenha os aliases agrupados sob uma entidade.

4. Pesquise amplamente por grupo de entidade. Para cada entidade, pesquise múltiplos aliases, variantes limpas, candidatos exatos de slug ou ID direto quando o banco de dados alvo os suportar, e consultas de nome curto contextualizadas, como <grupo> <nome curto>. Use rastreamento de consulta local por entidade; a desduplicação global de consultas pode privar entidades posteriores de aliases comuns.

5. Considere um planejador de recuperação LLM quando a recuperação determinística estiver vazia ou fraca. O planejamento é separado da reclassificação: peça IDs diretos, slugs de URL, sondas de nome exato, aliases e pesquisas contextuais. Mantenha as sondas limitadas e de alta precisão.

6. Mescle candidatos por identidade de registro estável. Deduplique por id de perfil, slug, URL canônica, id de banco de dados ou outra chave estável. Preserve cada consulta e fonte que encontrou o candidato, em vez de manter apenas o caminho de maior pontuação.

7. Enriqueça candidatos antes da reclassificação. Reúna evidências conceituais entre identidade, proveniência, utilidade, ambiguidade e confiança. O reclassificador nunca deve ser solicitado a escolher apenas a partir de nomes.

8. Use reclassificação LLM limitada apenas para candidatos genuinamente concorrentes. Continue apenas quando outra passagem puder melhorar materialmente a cobertura ou distinguir identidades prováveis.

9. Mostre alternativas significativas quando elas puderem mudar a decisão ou permitir correção; uma correspondência exata de ID autoritativa não precisa de candidatos fabricados.

10. Trate não resolvido e incerto como resultados de primeira classe. Prefira needs review, no plausible match ou ambiguous em vez de preencher silenciosamente um falso positivo de alta utilidade.

Nomes Parciais e Instruções Difusas

Quando uma consulta contém principalmente primeiros nomes, aliases curtos, iniciais ou nomes parciais de organizações, não trate resultados brutos do banco de dados como suficientes. Expanda ou classifique quando termos de agrupamento, intenção de perfil completo ou nomes de um token tornarem os resultados diretos não confiáveis.

Mantenha duas representações da consulta:

• originalQuery: a instrução completa do usuário e contexto.
• entityHints: a lista extraída de nomes de candidatos ou aliases a serem resolvidos.

O modelo de expansão deve ver ambas. Peça a ele para inferir o contexto compartilhado provável e retornar entidades concretas com aliases agrupados. Para cada entidade expandida, preserve um rótulo mais aliases, depois pesquise esses aliases dentro desse ramo de entidade. O caminho de pesquisa direta ainda pode ser executado para nomes exatos simples, mas não deve suprimir a expansão quando a cobertura depender da inferência de identidades completas a partir de dicas parciais.

A cobertura é separada do volume de resultados. Cinco dicas solicitadas que produzem muitos candidatos brutos não estão resolvidas até que cada dica seja mapeada para uma entidade selecionada ou um resultado explícito de não resolvido/ambíguo. Rastreie expectedCount, resolvedCount, ambiguousCount e unresolvedHints ou campos equivalentes.

Planejamento de Recuperação e Reparo de Lacunas

Não confie em um reclassificador para resgatar registros que a recuperação nunca retornou. Divida o envolvimento do LLM em funções separadas:

• Modelo de expansão: "Quem ou quais são as entidades alvo?"
• Planejador de recuperação ou modelo de reparo: "Quais IDs exatos, slugs, URLs diretas, aliases e sondas de pesquisa o recuperador deve tentar para este alvo?"
• Modelo de reclassificador: "Dados esses candidatos enriquecidos, qual é o registro correto?"

Use o planejamento de recuperação apenas quando slugs ou IDs diretos puderem recuperar um registro faltante, ou quando uma entidade não tiver candidatos, dados utilizáveis ou apenas correspondências fracas/nomes comuns. Dê ao planejador a consulta original, aliases agrupados, sondas tentadas, falhas de fonte e restrições relevantes de fonte. Ele deve retornar sondas, não uma decisão de identidade.

Mantenha o reparo limitado e proporcional. Execute recuperação determinística em sondas úteis, mescle candidatos recuperados e marque uma entidade como não resolvida quando pesquisas adicionais for improvável de mudar a resposta.

Logging e Fanout

Registre a proveniência da fonte, IDs selecionados, ambiguidade e cobertura em proporção à tarefa. Evite payloads privados brutos. Quando grupos de entidades independentes já estão sendo processados concorrentemente, mantenha o estado do ramo isolado e mescle deterministicamente; não introduza fanout, infraestrutura de telemetria ou novas tentativas apenas para satisfazer este skill.

Modelo de Evidências

Mantenha as evidências conceituais e portáteis. Não se adapte demais aos campos de um único site.

• Evidência de identidade: correspondência de nome exata ou ID, aliases, nomes artísticos, nomes legais, variantes de romanização, tokens compartilhados, tokens primários faltantes, correspondência de contexto, relação conhecida de organização/grupo e nomes conflitantes.
• Evidência de proveniência: qual consulta encontrou o candidato, se veio de pesquisa, slug exato, URL direta, ID de banco de dados, busca de API, resultado da web, fonte fornecida pelo usuário, sonda de planejador de recuperação ou uma passagem de recuperação.
• Evidência de utilidade: número de imagens, completude do perfil, atividade, popularidade, visualizações, votos, contagem de listas, contagem de funcionários, contagem de relacionamentos, status verificado, recência e se o registro possui mídia ou metadados utilizáveis para a tarefa.
• Evidência de ambiguidade: nome curto/comum, correspondência apenas de sobrenome, iniciais, registros duplicados, páginas de grupo/projeto, páginas "e os", registros esparsos, aliases conflitantes, nomes antigos, organizações mescladas, subsidiárias ou figuras públicas com nomes semelhantes.
• Evidência de confiança: candidato selecionado, candidatos segundos colocados, motivo do reclassificador, status não resolvido, sinalizador de necessidade de revisão humana e status de cobertura para a consulta original.

Regras de Reclassificação

Use reclassificação LLM quando a ambiguidade genuína a justificar, limitada por evidências de fonte e um orçamento apropriado à tarefa.

• Dê ao reclassificador a consulta original, rótulo de entidade resolvida, aliases, nomes/IDs/URLs de candidatos, proveniência, evidências de identidade, evidências de utilidade e avisos de ambiguidade.
• Instrua-o a escolher identidade antes de utilidade. Ele não deve selecionar um candidato rico em imagens ou popular se a evidência de identidade for fraca.
• Para candidatos com plausível mesma identidade, deixe a utilidade decidir. Registros públicos de nome artístico ou nome de marca podem ser melhores que registros de nome legal se tiverem evidências mais fortes relevantes para a tarefa.
• Trate aliases de um token como ambíguos, a menos que apoiados por contexto, ID/slug exato, sobreposição de alias mais rica ou evidência externa forte.
• Evite regras de aceitação duras. Um acerto de alias direto é um sinal, não uma prova.
• Evite regras de rejeição duras. Registros romanizados, renomeados, esparsos ou de nome artístico podem parecer incompletos, mas ainda podem estar corretos.
• Se um candidato igualmente bem suportado tiver utilidade de tarefa substancialmente melhor, exponha-o ou realize uma comparação adicional justificada em vez de substituir silenciosamente a evidência de identidade.
• Registre ou exiba o motivo do candidato selecionado e mantenha alternativas visíveis.

Modos de Falha

Use estes como verificações de revisão quando um resolvedor "quase funciona", mas parece errado.

• A pesquisa exata no banco de dados pode perder registros reais. Sonde slugs exatos, URLs diretas, IDs ou endpoints alternativos quando disponíveis.
• Nomes curtos criam falsos positivos. Lisa, Rose, Sunny, Tiffany, Yuri e nomes de um token semelhantes precisam de pesquisas contextuais e avisos de ambiguidade.
• Nomes legais podem ser registros de utilidade piores. Nomes públicos/artísticos ou nomes de marca podem ter o perfil mais completo, mais imagens ou metadados mais atuais.
• Sinais de utilidade são poderosos, mas inseguros sozinhos. Contagens, votos, visualizações e popularidade devem desempatar apenas após a plausibilidade da identidade.
• Aliases compostos são contexto útil, mas frequentemente strings de busca literais ruins. Divida-os em aliases preservando a identidade do grupo.
• Lógica de aceitação direta dura é frágil. Pode capturar um duplicado genérico só porque um alias correspondeu.
• Portões de identidade duros são frágeis. Podem ocultar registros corretos quando os nomes são esparsos, traduzidos, romanizados, renomeados ou apenas de nome artístico.
• A contagem de cobertura não é correção. Encontrar 6 de 6 entidades não é sucesso se um registro selecionado for a pessoa ou organização errada.
• A desduplicação global de consultas pode privar entidades posteriores. Aliases comuns devem ser rastreados por grupo de entidade.
• A instabilidade da fonte faz parte do resultado. Timeouts, 403s, 404s, novas tentativas e dados parciais devem ser exibidos na proveniência ou logs de depuração.
• Reclassificadores não podem corrigir candidatos faltantes. Se um ramo alvo tiver zero candidatos, insira planejamento de recuperação ou reparo antes da reclassificação, em vez de esperar que o reclassificador infira um registro oculto.
• Texto de instrução pode envenenar a pesquisa literal. Remova frases de tarefa da consulta de pesquisa, preservando-as como contexto para expansão e reclassificação.
• Resultados diretos rápidos podem suprimir a necessidade de expansão. Verifique a cobertura mesmo quando os primeiros resultados parecerem corretos.

Nota cultural: Ao traduzir termos como "slug", "alias", "handle", "token" ou "reranker", mantenha o termo original ou forneça um equivalente técnico amplamente aceito. Optou-se por manter termos como "slug", "alias", "handle" e "reranker" por serem amplamente reconhecidos na área.