Moonweave-Research/ref-verify

ref-verify — Guardián Contra Alucinaciones en Citas

El fallo específico que esta habilidad previene: los LLMs describen el contenido de un artículo a partir de datos de entrenamiento recordados en lugar de lo que realmente dice el resumen. A un artículo se le atribuyen hallazgos que no contiene, o se le cita por afirmaciones que no aparecen en ninguna parte del texto. La solución es una regla aplicada consistentemente:

Cada declaración de contenido sobre un artículo debe provenir de una fuente obtenida en vivo — resumen para afirmaciones generales/de titulares, texto completo para afirmaciones de mecanismo/implementación/procedimiento — citada o parafraseada textualmente. Si no puedes obtener la fuente requerida, dilo explícitamente — nunca llenes el vacío con descripción recordada, y nunca permitas que una coincidencia temática de resumen reemplace una afirmación de nivel de mecanismo.

---

Decisión de Modo

Elige el modo antes de hacer cualquier trabajo. La elección controla el costo y la profundidad.

¿El usuario proporciona DOI(s) para verificación de cordura?
  └─ ≤10 refs → Quick Screen todas
  └─ >10 refs → Quick Screen todas; Full Audit solo resultados MISMATCH/DEAD

¿El usuario dice "encuentra artículos sobre X" o "cita artículos que respalden la afirmación Y"?
  └─ Full Audit (buscar desde cero requiere verificación de contenido)

¿El usuario dice "verifica/revisa mi lista de referencias" o auditoría previa a envío?
  └─ ≤5 refs  → Full Audit todas
  └─ >5 refs  → Quick Screen todas primero; Full Audit MISMATCH/DEAD + cualquier ref
                 citada para una afirmación fáctica específica

¿El usuario está escribiendo y añade una sola cita de memoria?
  └─ Quick Screen mínimo; Full Audit si cita para una afirmación específica

La parte costosa es Full Audit (5 capas, obtención de evidencia a nivel de fuente). Quick Screen cuesta ~5s por artículo. Solo escala a Full Audit cuando la tarea realmente requiere verificación de contenido.

---

Motor Ejecutable

Usa esto como un flujo de trabajo a nivel de habilidad. No construyas ni requieras MCP para esta ruta. La CLI es un motor de ejecución que la habilidad puede llamar desde la terminal; el protocolo manual sigue siendo la alternativa y la fuente de verdad para las capas que la CLI aún no cubre.

Verificación de Disponibilidad de CLI

Antes de una verificación basada en DOI, verifica si el motor ejecutable está disponible:

ref-verify --help

npx skills add no instala la CLI de Python. Si el script de consola no está disponible, no lo trates como un resultado de verificación.

Si el script de consola no está disponible pero el código fuente del repositorio está presente, usa:

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

Si ambos comandos fallan, sigue el protocolo manual alternativo a continuación. No finjas que la CLI se ejecutó, y no inventes un resultado de memoria.

Flujo de trabajo CLI primero

Usa la CLI primero cuando el usuario proporcione un DOI o pregunte si un resumen vinculado a un DOI respalda una afirmación fáctica específica. El alcance actual de la CLI es verificación de metadatos de CrossRef más comprobaciones de afirmaciones de resumen vinculadas a DOI. Las comprobaciones de afirmaciones usan CrossRef primero, luego OpenAlex, Semantic Scholar y PubMed vinculados a DOI como alternativas cuando CrossRef no tiene resumen.

Pantalla de metadatos de CrossRef:

ref-verify verify-doi <doi> \
  --title "<título proporcionado>" \
  --first-author <apellido-del-primer-autor-proporcionado> \
  --year <año-proporcionado> \
  --json

Alternativa con checkout de fuente:

PYTHONPATH=src python3 -m ref_verify.cli verify-doi <doi> \
  --title "<título proporcionado>" \
  --first-author <apellido-del-primer-autor-proporcionado> \
  --year <año-proporcionado> \
  --json

verify-doi sale con código 0 solo para PASS; WARN y REJECT devuelven código no cero. Proporcionar solo un DOI verifica que CrossRef resuelva, pero no es suficiente para pasar la verificación de metadatos.

Enruta el resultado:

• PASS: informa la coincidencia de metadatos, luego continúa con la resolución de página de destino Layer 4 del DOI y las comprobaciones de retractación Layer 5 cuando el modo seleccionado lo requiera.
• WARN: informa los metadatos faltantes o débiles, luego continúa con la alternativa manual para las capas faltantes en lugar de aceptar silenciosamente la referencia.
• REJECT: deja de usar esa cita como verificada; informa la discrepancia y pide un DOI o cita corregidos a menos que el usuario quiera explícitamente alternativas.

Comprobación de afirmación única contra un resumen de DOI:

ref-verify check-claim <doi> --claim "<afirmación fáctica específica>" --json

Alternativa con checkout de fuente:

PYTHONPATH=src python3 -m ref_verify.cli check-claim <doi> --claim "<afirmación fáctica específica>" --json

Por defecto, check-claim usa CrossRef primero. Si CrossRef no tiene resumen, intenta fuentes alternativas OpenAlex, Semantic Scholar y PubMed vinculadas a DOI. Usa --source crossref, --source openalex, --source semantic-scholar o --source pubmed para depuración específica de fuente. La selección explícita de fuente no CrossRef omite CrossRef, por lo que puede aislar un fallo de OpenAlex, Semantic Scholar o PubMed.

Enruta el resultado:

• ACCEPT: cita la evidencia de la CLI y continúa cualquier resolución de DOI manual requerida, verificación de segunda fuente y capas de retractación.
• WARN o PARTIAL: informa lo que la fuente de resumen seleccionada respaldó y no respaldó, luego continúa con la alternativa manual cuando se requieran más capas.
• UNVERIFIABLE: no hubo evidencia de resumen confiable vinculada a DOI disponible de las fuentes de CLI intentadas. Continúa con la cadena de alternativa manual a continuación en lugar de tratar la afirmación como rechazada o respaldada.

CLI ACCEPT es solo evidencia a nivel de resumen. Si la afirmación describe un mecanismo, implementación o procedimiento, no promuevas ese resultado al veredicto de Full Audit; clasifica la afirmación en Layer 3 y obtén primero la evidencia de texto completo requerida.

Para salida JSON, usa abstract_source, source_attempts y error_code para decidir el siguiente paso:

• CLAIM_SUPPORTED: se encontró respaldo explícito en el resumen.
• CLAIM_NOT_EXPLICIT: un resumen estaba disponible, pero la afirmación no estaba respaldada explícitamente.
• CLAIM_AMBIGUOUS: existe evidencia numérica o contexto, pero la vinculación es ambigua.
• NO_ABSTRACT: las fuentes vinculadas a DOI intentadas no proporcionaron texto de resumen.
• DOI_NOT_FOUND: la fuente seleccionada no encontró un registro vinculado al DOI.
• DOI_MISMATCH: el registro vinculado al DOI primario o explícitamente seleccionado no coincidía con el DOI solicitado.
• SOURCE_API_ERROR, SOURCE_TIMEOUT, SOURCE_RATE_LIMITED, SOURCE_UNSUPPORTED: la consulta de fuente falló, excedió el tiempo de espera, fue limitada en tasa o no pudo ser utilizada.

La CLI no reemplaza la resolución de página de destino Layer 4 del DOI, las comprobaciones de existencia de dos fuentes ni las comprobaciones de retractación. Continúa con el protocolo manual para esas capas cuando el modo seleccionado lo requiera.

---

Quick Screen — verificación de cordura de metadatos + DOI

Usa cuando el usuario proporciona un DOI o cita completa y quiere una verificación de cordura.

1. Consulta CrossRef: https://api.crossref.org/works/{DOI}
2. Compara el título devuelto + el apellido del primer autor con lo que el usuario proporcionó
3. Obtén https://doi.org/{DOI} — confirma que resuelve y aterriza en el artículo correcto
4. Informa una línea por referencia:

Smith et al. (2021) 10.1234/example — PASS (coincidencia de título/autor, DOI resuelve)
Jones (2019) 10.5678/other — MISMATCH (CrossRef: Jones & Lee 2019, no Jones solo)
Kim (2023) 10.9999/fake — DEAD DOI

Escala a Full Audit si: el DOI resuelve a un artículo diferente, cualquier campo no coincide, o el usuario está citando para una afirmación fáctica específica.

---

Full Audit — para búsqueda bibliográfica o verificación previa a envío

Usa cuando: se buscan artículos para respaldar una afirmación, o se hace un barrido final de citas.

Ejecuta las cinco capas por artículo. Las capas están ordenadas por lo que detectan — no te saltes ninguna.

Layer 1 — Existencia

Busca en dos fuentes de forma independiente:

• 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

Un artículo se confirma solo si los títulos coinciden esencialmente y el apellido del primer autor concuerda en dos fuentes.

• Acierto en dos fuentes → CONFIRMED
• Una fuente → SINGLE-SOURCE ⚠ — procede con precaución, anótalo en la salida
• Cero → NOT FOUND ✗ — detente; informa claramente; no inventes un sustituto

Layer 2 — Metadatos

Extrae de fuentes confirmadas y compara: título, todos los autores (apellidos), año, nombre completo de la revista, DOI, volumen/páginas (marca [NOT IN SOURCE] si ausente). Si algún campo difiere entre fuentes, muestra ambos — no elijas silenciosamente uno.

Layer 3 — Trazabilidad de Contenido ← la capa más importante

Aquí reside el valor central de la habilidad. El objetivo no es solo "¿existe este artículo?" sino "¿este artículo realmente contiene la afirmación que se le atribuye?"

Paso 0 — Clasifica la afirmación.

Antes de obtener cualquier cosa, clasifica qué tipo de afirmación se está verificando:

• Afirmación de titular/resumen — un hallazgo del tipo que los resúmenes suelen declarar (resultado general, cifra principal, conclusión general). La evidencia solo del resumen es una fuente legítima de verdad para esta clase.
• Afirmación de mecanismo/implementación/procedimiento — describe cómo funciona o se hizo algo: un mecanismo específico, algoritmo, arquitectura, parámetro, paso experimental, condición de control, o un valor numérico vinculado a una tabla/figura/sección de métodos en lugar del resultado resumido. Los resúmenes omiten rutinariamente este contenido incluso cuando el artículo lo respalda. Palabras clave: "mecanismo", "cómo", "arquitectura", "algoritmo", "implementación", "procedimiento", "protocolo", "parámetro", "grupo de control", "ablación", "tabla", "figura", o cualquier afirmación más específica de lo que un resumen de un párrafo declararía.

Si la afirmación es de clase mecanismo/implementación, una verificación solo de resumen no es suficiente incluso cuando el resumen es temáticamente correcto. Obtén el resumen como evidencia de existencia/coincidencia temática, pero no resuelvas el veredicto solo del resumen — continúa al Layer 3b a continuación.

Obtén el resumen usando este orden de prioridad:

1. CrossRef JSON sin procesar: https://api.crossref.org/works/{DOI} — verifica el campo abstract
2. OpenAlex: https://api.openalex.org/works/doi:{DOI}?mailto={contact_email} — reconstruye abstract_inverted_index
3. Semantic Scholar: agrega &fields=abstract a tu consulta de DOI S2
4. Alternativa de acceso abierto: https://api.unpaywall.org/v2/{DOI}?email={contact_email} — verifica is_oa y oa_locations
5. Alternativa de arXiv para preprints: https://export.arxiv.org/api/query?id_list={arxiv_id}
6. PubMed Central para artículos de ciencias de la vida: https://www.ncbi.nlm.nih.gov/pmc/articles/{PMCID}/

Para las API que requieren un correo electrónico de contacto, reemplaza {contact_email} con una dirección real autorizada por el usuario desde la configuración. No envíes una dirección de marcador de posición.

Después de obtener, verifica: ¿el resumen contiene la afirmación específica que se cita?

• El resumen contiene explícitamente la afirmación (cítala textualmente) → CONTENT: SUPPORTED
• El resumen trata sobre el tema pero no hace la afirmación específica → CONTENT: PARTIAL — cita lo que realmente dice
• El resumen contradice la afirmación → CONTENT: CONTRADICTED — no uses esta cita
• El resumen no es accesible después de intentar todas las fuentes → CONTENT: UNVERIFIABLE — el usuario debe verificar el texto completo
• La afirmación es de clase mecanismo/implementación y no se pudo obtener el texto completo después de intentar todas las fuentes del Layer 3b → CONTENT: ABSTRACT-ONLY — texto completo no disponible, verificación insuficiente. Esta etiqueta nunca debe ser promovida a SUPPORTED/ACCEPT.

La regla que no se puede relajar: si describes lo que un artículo "muestra" o "demuestra" o "reporta", debes citar o parafrasear directamente el texto de la fuente obtenida a la profundidad requerida. Resumir de memoria no está permitido incluso si te sientes seguro.

Layer 3b — Confirmación de Texto Completo (solo para afirmaciones de clase mecanismo/implementación)

Requerido siempre que el Paso 0 clasificó la afirmación como de clase mecanismo/implementación, o siempre que el veredicto del resumen sea PARTIAL para una afirmación más específica que el nivel de resumen del resumen. Salta solo para afirmaciones de titular que recibieron CONTENT: SUPPORTED directamente del resumen.

Obtén el cuerpo del artículo en este orden de prioridad, deteniéndote en el primer éxito:

1. PDF local de Zotero — si una biblioteca de Zotero está configurada, consulta su base de datos para este DOI, resuelve la clave de adjunto y lee el PDF vinculado. Un valor predeterminado común es ~/Zotero/zotero.sqlite con adjuntos bajo ~/Zotero/storage/{key}/; descubre la ruta real en lugar de asumirla.
2. Vault de research-wiki — cuando la habilidad research-wiki está disponible, busca en su vault configurado una copia de texto completo ya ingerida. No asumas una ruta de vault específica de la máquina.
3. Enlace de acceso abierto — resuelve y obtén el texto completo real (no solo una bandera de disponibilidad):
   • Unpaywall: https://api.unpaywall.org/v2/{DOI}?email={contact_email} → obtén best_oa_location.url_for_pdf (o cualquier oa_locations[].url_for_pdf).
   • arXiv: https://export.arxiv.org/api/query?id_list={arxiv_id} → obtén el artículo completo, no solo el campo <summary>.
4. Fallo — si ninguno de los anteriores produce un texto completo legible, no trates el resumen como suficiente. Aplica la etiqueta CONTENT: ABSTRACT-ONLY definida anteriormente.

Cuando se obtiene el texto completo, cita el pasaje que respalda, respalda parcialmente o contradice la afirmación. Para una afirmación de mecanismo/implementación, CONTENT: SUPPORTED requiere una cita de texto completo — una coincidencia temática a nivel de resumen no puede satisfacerla.

Layer 4 — Resolución de DOI

Obtén https://doi.org/{DOI}. Confirma que la página de destino coincide con el artículo esperado. Un 403 (bloqueado por bot) de un slug de URL que contiene el título y el volumen no es un enlace muerto — anótalo como protegido por paywall. Una redirección a una página no relacionada es un fallo crítico.

Layer 5 — Retractación

Busca "{apellido del primer autor}" "{nombre de la revista}" retraction y verifica la página de destino del DOI en busca de banners de retractación. Un artículo retractado no debe usarse como fuente primaria.

---

Formato de Salida

Quick Screen: una línea por referencia (ver arriba).

Full Audit: una tarjeta por artículo, luego una tabla resumen.

AUDITORÍA DE REFERENCIAS
────────────────────────────────────────────────
Artículo: [Título de fuente en vivo — no de memoria]
DOI:      [DOI] — [✓ Resuelve | ✗ Muerto | ✗ Artículo incorrecto | ⚠ Protegido por paywall-403]
Autores:  [Apellidos completos de fuente en vivo]
Año:      [Año verificado]
Revista:  [Nombre completo de la revista]

Capa 2 (Metadatos):
  Título: [Coincide / Discrepancia: fuente A vs fuente B]
  Autores: [Coinciden / Discrepancia: ...]
  Año:     [Coincide / Discrepancia: ...]
  Revista: [Coincide / Discrepancia: ...]
  Vol/Pág: [Valores o [NOT IN SOURCE]]

Capa 3 (Trazabilidad de Contenido):
  Afirmación verificada: "[cita textual de la afirmación del usuario]"
  Clasificación de afirmación: [Titular | Mecanismo/Implementación]
  Evidencia de resumen: [SUPPORTED | PARTIAL | CONTRADICTED | UNVERIFIABLE | ABSTRACT-ONLY]
  Texto de evidencia: "[cita textual del resumen o texto completo]"
  [Si se obtuvo texto completo, cita adicional requerida para afirmaciones de clase mecanismo/implementación]

Capa 4 (Resolución de DOI):
  Página de destino: [URL] — [Estado]

Capa 5 (Retractación):
  Estado: [No retractado | RETRACTADO — no usar]

Veredicto: [APROBADO | ADVERTENCIA: explicación | RECHAZADO: razón]

---

Notas Finales

• No invocar para formatear referencias en estilo APA/IEEE, explicaciones de temas generales, preguntas de estilo de citación o edición de prosa.
• El motor ejecutable CLI es opcional pero preferido cuando está disponible. El protocolo manual es la alternativa autorizada.
• La regla de oro: cada afirmación debe tener una fuente obtenida. No confíes en la memoria del LLM.