Moonweave-Research/ref-verify

ref-verify — Guardião de Alucinações de Referências

A falha específica que esta skill previne: LLMs descrevem o conteúdo de artigos a partir de dados de treinamento lembrados, em vez do que o resumo realmente diz. Um artigo recebe conclusões que não contém, ou é citado por afirmações que não aparecem em lugar algum no texto. A correção é uma regra aplicada de forma consistente:

Toda afirmação de conteúdo sobre um artigo deve vir de uma fonte obtida ao vivo — resumo para afirmações principais/gerais, texto completo para afirmações de mecanismo/implementação/procedimento — citada ou parafraseada textualmente. Se você não puder obter a fonte necessária, diga isso explicitamente — nunca preencha a lacuna com descrição lembrada, e nunca deixe uma correspondência de resumo temático substituir uma afirmação de nível de mecanismo.

---

Decisão de Modo

Escolha o modo antes de fazer qualquer trabalho. A escolha controla custo e profundidade.

O usuário fornece DOI(s) para verificação de sanidade?
  └─ ≤10 refs → Verificação Rápida em todas
  └─ >10 refs → Verificação Rápida em todas; Auditoria Completa apenas em resultados INCOMPATÍVEL/MORTO

O usuário diz "encontre artigos sobre X" ou "cite artigos apoiando a afirmação Y"?
  └─ Auditoria Completa (pesquisar do zero requer verificação de conteúdo)

O usuário diz "verifique/audite minha lista de referências" ou auditoria pré-submissão?
  └─ ≤5 refs  → Auditoria Completa em todas
  └─ >5 refs  → Verificação Rápida em todas primeiro; Auditoria Completa em INCOMPATÍVEL/MORTO + qualquer ref
                 citada por uma afirmação factual específica

O usuário está escrevendo e adiciona uma única citação de memória?
  └─ Verificação Rápida mínima; Auditoria Completa se citando para uma afirmação específica

A parte cara é a Auditoria Completa (5 camadas, busca de evidências em profundidade de fonte). A Verificação Rápida custa ~5s por artigo. Só escale para Auditoria Completa quando a tarefa realmente exigir verificação de conteúdo.

---

Motor Executável

Use isso como um fluxo de trabalho de nível de skill. Não construa ou exija MCP para este caminho. A CLI é um motor de execução que a skill pode chamar do terminal; o protocolo manual continua sendo o fallback e a fonte da verdade para camadas que a CLI ainda não cobre.

Verificação de Disponibilidade da CLI

Antes de uma verificação baseada em DOI, veja se o motor executável está disponível:

ref-verify --help

npx skills add não instala a CLI Python via pip. Se o script de console estiver indisponível, não trate isso como um resultado de verificação.

Se o script de console estiver indisponível, mas o código fonte do repositório estiver presente, use:

PYTHONPATH=src python3 -m ref_verify.cli --help

Se ambos os comandos falharem, siga o protocolo de fallback manual abaixo. Não finja que a CLI foi executada e não invente um resultado de memória.

Fluxo de trabalho primeiro via CLI

Use a CLI primeiro quando o usuário fornecer um DOI ou perguntar se um resumo vinculado a um DOI apoia uma afirmação factual específica. O escopo atual da CLI é a verificação de metadados CrossRef mais verificações de afirmações baseadas em resumo vinculado a DOI. As verificações de afirmações usam CrossRef primeiro, depois OpenAlex vinculado a DOI, Semantic Scholar e PubMed como fallback quando o CrossRef não tem resumo.

Verificação de metadados CrossRef:

ref-verify verify-doi <doi> \
  --title "<título fornecido>" \
  --first-author <sobrenome-do-primeiro-autor-fornecido> \
  --year <ano-fornecido> \
  --json

Fallback com checkout do código fonte:

PYTHONPATH=src python3 -m ref_verify.cli verify-doi <doi> \
  --title "<título fornecido>" \
  --first-author <sobrenome-do-primeiro-autor-fornecido> \
  --year <ano-fornecido> \
  --json

verify-doi sai com código 0 apenas para PASS; WARN e REJECT retornam código diferente de zero. Fornecer apenas um DOI verifica se o CrossRef resolve, mas não é suficiente para passar na verificação de metadados.

Direcione o resultado:

• PASS: reporte a correspondência de metadados, depois continue a Camada 4 de resolução de página de destino do DOI e Camada 5 de verificações de retratação quando o modo selecionado as exigir.
• WARN: reporte os metadados ausentes ou fracos, depois continue o fallback manual para as camadas ausentes em vez de aceitar silenciosamente a referência.
• REJECT: pare de usar essa citação como verificada; reporte a incompatibilidade e peça um DOI ou citação corrigidos, a menos que o usuário queira explicitamente alternativas.

Verificação de afirmação única contra o resumo de um DOI:

ref-verify check-claim <doi> --claim "<afirmação factual específica>" --json

Fallback com checkout do código fonte:

PYTHONPATH=src python3 -m ref_verify.cli check-claim <doi> --claim "<afirmação factual específica>" --json

Por padrão, check-claim usa CrossRef primeiro. Se o CrossRef não tiver resumo, ele tenta fontes de fallback OpenAlex vinculado a DOI, Semantic Scholar e PubMed. Use --source crossref, --source openalex, --source semantic-scholar ou --source pubmed para depuração específica de fonte. A seleção explícita de fonte diferente de CrossRef ignora CrossRef, para que possa isolar uma falha do OpenAlex, Semantic Scholar ou PubMed.

Direcione o resultado:

• ACCEPT: cite a evidência da CLI e continue qualquer resolução manual de DOI necessária, verificação de existência em segunda fonte e camadas de retratação.
• WARN ou PARTIAL: reporte o que a fonte de resumo selecionada apoiou e não apoiou, depois continue o fallback manual quando mais camadas forem necessárias.
• UNVERIFIABLE: nenhuma evidência de resumo confiável vinculada a DOI estava disponível nas fontes da CLI tentadas. Continue a cadeia de fallback manual abaixo em vez de tratar a afirmação como rejeitada ou apoiada.

A aceitação da CLI (ACCEPT) é apenas evidência de nível de resumo. Se a afirmação descrever um mecanismo, implementação ou procedimento, não promova esse resultado para o veredito da Auditoria Completa; classifique a afirmação na Camada 3 e obtenha a evidência de texto completo necessária primeiro.

Para saída JSON, use abstract_source, source_attempts e error_code para decidir o próximo passo:

• CLAIM_SUPPORTED: suporte explícito do resumo encontrado.
• CLAIM_NOT_EXPLICIT: um resumo estava disponível, mas a afirmação não foi explicitamente apoiada.
• CLAIM_AMBIGUOUS: evidência numérica ou contexto existe, mas a vinculação é ambígua.
• NO_ABSTRACT: as fontes vinculadas a DOI tentadas não forneceram texto do resumo.
• DOI_NOT_FOUND: a fonte selecionada não encontrou um registro vinculado ao DOI.
• DOI_MISMATCH: o registro vinculado ao DOI primário ou explicitamente selecionado não correspondeu ao DOI solicitado.
• SOURCE_API_ERROR, SOURCE_TIMEOUT, SOURCE_RATE_LIMITED, SOURCE_UNSUPPORTED: a consulta à fonte falhou, expirou, foi limitada por taxa ou não pôde ser usada.

A CLI não substitui a Camada 4 de resolução de página de destino do DOI, verificações de existência em duas fontes ou verificações de retratação. Continue o protocolo manual para essas camadas quando o modo selecionado as exigir.

---

Verificação Rápida — verificação de sanidade de metadados + DOI

Use quando o usuário fornecer um DOI ou citação completa e quiser uma verificação de sanidade.

1. Acesse CrossRef: https://api.crossref.org/works/{DOI}
2. Compare o título retornado + sobrenome do primeiro autor com o que o usuário forneceu
3. Busque https://doi.org/{DOI} — confirme que ele resolve e leva ao artigo correto
4. Reporte uma linha por referência:

Smith et al. (2021) 10.1234/example — PASS (título/autor correspondem, DOI resolve)
Jones (2019) 10.5678/other — INCOMPATÍVEL (CrossRef: Jones & Lee 2019, não Jones sozinho)
Kim (2023) 10.9999/fake — DOI MORTO

Escale para Auditoria Completa se: o DOI resolver para um artigo diferente, qualquer campo não corresponder, ou o usuário estiver citando para uma afirmação factual específica.

---

Auditoria Completa — para busca de literatura ou verificação pré-submissão

Use quando: pesquisando artigos para apoiar uma afirmação, ou fazendo uma varredura final de citações.

Execute todas as cinco camadas por artigo. As camadas são ordenadas pelo que detectam — não pule adiante.

Camada 1 — Existência

Pesquise duas fontes independentemente:

• CrossRef: https://api.crossref.org/works?query.bibliographic={título+autor}&rows=5
• Semantic Scholar: https://api.semanticscholar.org/graph/v1/paper/search?query={título+autor}&fields=title,authors,year,externalIds,abstract&limit=5
• arXiv para preprints: https://export.arxiv.org/api/query?search_query=ti:{título}&max_results=3

Um artigo só é confirmado se os títulos corresponderem essencialmente e o sobrenome do primeiro autor concordar em duas fontes.

• Acerto em duas fontes → CONFIRMADO
• Uma fonte → FONTE ÚNICA ⚠ — prossiga com cuidado, anote na saída
• Zero → NÃO ENCONTRADO ✗ — pare; reporte claramente; não invente um substituto

Camada 2 — Metadados

Extraia das fontes confirmadas e compare: título, todos os autores (sobrenomes), ano, nome completo do periódico, DOI, volume/páginas (marque [NÃO NA FONTE] se ausente). Se algum campo diferir entre as fontes, mostre ambos — não escolha silenciosamente um.

Camada 3 — Rastreabilidade de Conteúdo ← camada mais importante

É aqui que reside o valor central da skill. O objetivo não é apenas "este artigo existe" mas "este artigo realmente contém a afirmação que está sendo atribuída a ele."

Passo 0 — Classifique a afirmação.

Antes de buscar qualquer coisa, classifique que tipo de afirmação está sendo verificada:

• Afirmação principal/geral — uma descoberta do tipo que os resumos convencionalmente declaram (resultado geral, número principal, conclusão geral). Evidência de resumo apenas é uma fonte legítima da verdade para esta classe.
• Afirmação de mecanismo/implementação/procedimento — descreve como algo funciona ou foi feito: um mecanismo específico, algoritmo, arquitetura, parâmetro, passo experimental, condição de controle, ou um valor numérico ligado a uma tabela/figura/seção de métodos em vez do resultado do resumo. Os resumos rotineiramente omitem esse conteúdo mesmo quando o artigo o suporta. Palavras-sinal: "mecanismo," "como," "arquitetura," "algoritmo," "implementação," "procedimento," "protocolo," "parâmetro," "grupo controle," "ablação," "tabela," "figura," ou qualquer afirmação mais específica do que um resumo de um parágrafo declararia.

Se a afirmação for de classe mecanismo/implementação, uma verificação apenas de resumo não é suficiente mesmo quando o resumo está tematicamente correto. Busque o resumo como evidência de existência/correspondência temática, mas não resolva o veredito apenas do resumo — continue para a Camada 3b abaixo.

Busque o resumo usando esta ordem de prioridade:

1. CrossRef JSON bruto: https://api.crossref.org/works/{DOI} — verifique o campo abstract
2. OpenAlex: https://api.openalex.org/works/doi:{DOI}?mailto={email_contato} — reconstrua abstract_inverted_index
3. Semantic Scholar: acrescente &fields=abstract à sua consulta de DOI S2
4. Fallback de acesso aberto: https://api.unpaywall.org/v2/{DOI}?email={email_contato} — verifique is_oa e oa_locations
5. Fallback arXiv para preprints: https://export.arxiv.org/api/query?id_list={arxiv_id}
6. PubMed Central para artigos de ciências da vida: https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/

Para APIs que exigem um e-mail de contato, substitua {email_contato} por um endereço real e autorizado pelo usuário da configuração. Não envie um endereço placeholder.

Após buscar, verifique: o resumo contém a afirmação específica que está sendo citada?

• Resumo contém explicitamente a afirmação (cite-a textualmente) → CONTEÚDO: SUPORTADO
• Resumo é sobre o tema, mas não faz a afirmação específica → CONTEÚDO: PARCIAL — cite o que realmente diz
• Resumo contradiz a afirmação → CONTEÚDO: CONTRADITO — não use esta citação
• Resumo não acessível após tentar todas as fontes → CONTEÚDO: INVERIFICÁVEL — usuário deve verificar o texto completo
• Afirmação é de classe mecanismo/implementação e o texto completo não pôde ser obtido após tentar todas as fontes da Camada 3b → CONTEÚDO: APENAS RESUMO — texto completo indisponível, verificação insuficiente. Este rótulo nunca deve ser atualizado para SUPORTADO/ACEITO.

A regra que não pode ser relaxada: se você descrever o que um artigo "mostra" ou "demonstra" ou "relata", você deve citar ou parafrasear diretamente o texto da fonte obtida na profundidade necessária. Resumir de memória não é permitido mesmo se você se sentir confiante.

Camada 3b — Confirmação de Texto Completo (apenas para afirmações de classe mecanismo/implementação)

Necessária sempre que o Passo 0 classificou a afirmação como de classe mecanismo/implementação, ou sempre que o veredito do resumo for PARCIAL para uma afirmação mais específica do que o nível de resumo do resumo. Pule apenas para afirmações principais que receberam CONTEÚDO: SUPORTADO diretamente do resumo.

Busque o corpo do artigo nesta ordem de prioridade, parando no primeiro sucesso:

1. PDF local do Zotero — se uma biblioteca Zotero estiver configurada, consulte seu banco de dados para este DOI, resolva a chave do anexo e leia o PDF vinculado. Um padrão comum é ~/Zotero/zotero.sqlite com anexos em ~/Zotero/storage/{key}/; descubra o caminho real em vez de assumi-lo.
2. vault do research-wiki — quando a skill research-wiki estiver disponível, pesquise seu vault configurado em busca de uma cópia do texto completo já ingerido. Não assuma um caminho de vault específico da máquina.
3. Link de acesso aberto — resolva e busque o texto completo real (não apenas um sinalizador de disponibilidade):
   • Unpaywall: https://api.unpaywall.org/v2/{DOI}?email={email_contato} → busque best_oa_location.url_for_pdf (ou qualquer oa_locations[].url_for_pdf).
   • arXiv: https://export.arxiv.org/api/query?id_list={arxiv_id} → busque o artigo completo, não apenas o campo <summary>.
4. Falha — se nenhum dos acima produzir um texto completo legível, não trate o resumo como suficiente. Aplique o rótulo CONTEÚDO: APENAS RESUMO definido acima.

Quando o texto completo for obtido, cite a passagem que suporta, suporta parcialmente, ou contradiz a afirmação. Para uma afirmação de mecanismo/implementação, CONTEÚDO: SUPORTADO requer uma citação do texto completo — uma correspondência temática de nível de resumo não pode satisfazê-la.

Camada 4 — Resolução de DOI

Busque https://doi.org/{DOI}. Confirme que a página de destino corresponde ao artigo esperado. Um 403 (bloqueado por bot) de um slug de URL contendo o título e o volume não é um link morto — anote como atrás de paywall. Um redirecionamento para uma página não relacionada é uma falha crítica.

Camada 5 — Retratação

Pesquise "{sobrenome do primeiro autor}" "{nome do periódico}" retraction e verifique a página de destino do DOI em busca de banners de retratação. Um artigo retratado não deve ser usado como fonte primária.

---

Formato de Saída

Verificação Rápida: uma linha por referência (veja acima).

Auditoria Completa: um cartão por artigo, depois uma tabela resumo.

AUDITORIA DE REFERÊNCIA
────────────────────────────────────────────────
Artigo:  [Título da fonte ao vivo — não de memória]
DOI:     [DOI] — [✓ Resolve | ✗ Morto | ✗ Artigo errado | ⚠ Paywall-403]
Autores: [Li

...[truncado para tradução]