zhichao1208/reduce-hallucination

¿Qué hace reduce-hallucination?

Convierte las técnicas verificadas que la ciencia del interrogatorio utiliza para hacer que un testigo informado diga la verdad en una auditoría estándar para agentes LLM. Cada nodo LLM es un testigo. La transferencia entre nodos es la transcripción del testimonio. Las correcciones del usuario y los registros de tareas son evidencia física.

La teoría y la evidencia viven en references/. Lee references/research-map.md para conocer las citas detrás de cada afirmación.

Tres reglas de hierro

1. No hay acusación sin evidencia (regla de Wellman). Cada hallazgo debe citar el prompt, esquema o salida real al que se refiere. Una sospecha sin una cita va a una lista "por verificar", no en los hallazgos.
2. Las señales superficiales no prueban la verdad. Un texto fluido, confiado y detallado no es más correcto que un texto escueto. Las personas detectan el engaño a partir del comportamiento aproximadamente al azar. Juzga solo el contenido: fundamentación, consistencia, si el fragmento citado existe.
3. La autocorrección necesita una nueva señal externa. "¿Estás seguro? Vuelve a comprobarlo" sin nueva evidencia degrada la precisión. Cada nueva comprobación debe inyectar resultados recuperados o la salida de un validador.

Los tres pilares de una buena cita

La calidad de la cita se descompone en tres verificaciones, en orden ascendente de dificultad y valor:

Pilar	Pregunta	Estado actual
Fiel	¿La cita es textualmente real y la afirmación no es fabricada?	En gran medida resoluble: coincidencia de cadena textual + abstención.
Relevante	¿La fuente está relacionada con la pregunta?	En gran medida resoluble: calidad de recuperación + sondeo de consistencia.
De apoyo	¿La fuente apoya la afirmación, vs la contradice, vs se mantiene neutral?	La frontera. Difícil, y la rara clase "contradicción" es donde los sistemas son más débiles.

Una cita que se resuelve en un pasaje real y relevante pero que en realidad no apoya la afirmación ("desfundamentación") es peor que ninguna cita, porque genera confianza sobre una afirmación incorrecta y desarma la única defensa funcional del revisor (verificar el contenido). Mostrar una cita sin verificarla en el backend hace que la alucinación sea más peligrosa, no menos.

Protocolo de auditoría

Fase 1 — interrogar a cada testigo (banderas rojas de prompt + esquema)

Para cada nodo LLM, ejecuta la lista de banderas rojas. Cada bandera es una violación de interrogatorio.

#	Bandera roja (qué buscar)	Por qué importa	Daño
R1	Un campo enumerado sin opción null / unknown; una instrucción unidireccional de "generar una confirmación de X".	Forzar una respuesta produce cumplimiento (análogo a una confesión falsa).	Adivinación forzada, fabricación confiada.
R2	La prosa concede una abstención ("usa null si falta") pero el esquema no tiene null.	El esquema gana, la abstención es nula.	Fabricación silenciosa.
R3	El prompt pide evidencia/cita, pero nada posterior la verifica.	Decir sin verificar enseña al modelo a fabricar citas más convincentes.	Anclajes falsos.
R4	Instrucciones direccionales: "sé conservador", "asume", "infiere de", "por defecto".	Presunción unidireccional; combinado con R1 produce sesgo sistemático.	Salida sesgada en una dirección.
R5	Un campo agregado sin unidad definida ("años totales", "puntuación general").	Una medición necesita su unidad declarada antes de poder ser fijada.	Desajuste de definición interpretado como error de extracción.
R6	Ejemplos de pocos disparos que no están en la tarea o que modelan razonamiento sin citas.	Los ejemplos establecen la expectativa de una respuesta "buena".	Enseña el estilo de salida incorrecto.
R7	El prompt afirma que el nodo puede hacer algo para lo que no tiene herramienta.	Premisa falsa.	Narración de proceso fabricada.
R8	Un "hecho" proporcionado por el usuario o un nodo ascendente, utilizado como verdad sin etiqueta de fuente.	Solo confrontar con evidencia verificada.	Contaminación de premisa.
R9	Una plantilla con un espacio obligatorio y sin rama vacía.	La versión en plantilla de forzar una respuesta.	Un espacio en blanco se llena con el valor más cercano.
R10	Revisión/reintento escritos de forma agresiva ("te equivocaste, arréglalo") sin nueva evidencia.	El adulamiento invierte respuestas correctas.	Respuestas correctas anuladas.

Registra cada una como: nodo | R# | texto citado | consecuencia en una línea.

Fase 2 — auditar la transcripción (límites entre nodos / flujo de datos)

Aquí es donde ocurre la mayoría de las alucinaciones en pipeline. Dibuja el flujo de datos y verifica cada borde:

1. ¿La incertidumbre cruza el límite? confianza / missing_fields / null / notas del nodo ascendente — ¿algo descendente los consume, o una plantilla los aplana en una afirmación? Busca incertidumbre "en punto muerto": producida pero nunca leída.
2. ¿Se pierde la procedencia? Un valor que el razonamiento ascendente admite como "asumido/inferido" se convierte en un hecho no marcado aguas abajo. El esquema debe llevar stated | inferred | absent.
3. ¿Se cruzan las categorías de hechos? Datos de configuración o requisitos representados como si el usuario/documento los hubiera afirmado.
4. ¿Un agregado cambia de unidad? "años médicos totales" aguas arriba se convierte en "años como título X" aguas abajo.
5. ¿Está el LLM haciendo cómputo determinista? Cálculos de fechas, sumas, conteos en un prompt deben pasar a un paso de código.

Fase 3 — coincidir con la evidencia física (cuando existen registros de tareas)

1. Extrae las salidas intermedias de los nodos para una muestra de tareas (prefiere aquellas con correcciones de usuario o fallos).
2. Compara la salida final vs la salida intermedia de cada nodo vs la entrada original, campo por campo; localiza qué límite perdió primero la verdad.
3. Encuentra declaraciones previas inconsistentes: el mismo campo contradiciéndose a sí mismo entre nodos.
4. Si las correcciones son direccionales (sistemáticamente en una dirección), vuelve a verificar las instrucciones direccionales de Fase-1 R4; el error aleatorio apunta más a la calidad de la entrada.
5. Clasifica honestamente: "información que nunca estuvo en la fuente" (una brecha de proceso, no una alucinación) vs "información que estaba en la entrada pero se expresó incorrectamente" (una alucinación real).

Fase 4 — correcciones clasificadas (por retorno de inversión)

Capa 1 — prompt / esquema (cambio estructural cero)

• Cada R1/R2 → agrega un enumerado null/unknown + una línea desestigmatizante ("X es una respuesta correcta y esperada").
• Cada R9 → agrega una rama vacía a la plantilla (la afirmación se convierte en una pregunta abierta).
• Cada R5 → divide la unidad, o genera un rango {floor, ceiling}.
• Cada R3 → agrega un triplete {value, source, evidence_quote} a los campos críticos.

Capa 2 — un validador de código determinista (costo LLM cero)

Validador	Verifica
Lista blanca de enumerados	El valor del campo está en el conjunto permitido.
Coincidencia textual de cita	evidence_quote existe textualmente en la fuente citada; si no, rechaza o degrada.
Consistencia entre campos	Los totales concilian; missing_fields no contradice los valores completados.
Cómputo de unidades	Diferencias de fecha / sumas hechas en código; el LLM solo hace extracción semántica.
Contrato de salida	Cada espacio de hecho visible para el usuario no está vacío y proviene de un campo fuente permitido.

Colócalo antes de cualquier nodo que produzca contenido visible para el usuario. En caso de fallo, escribe una bandera de respaldo y redirige a una pregunta abierta o a un humano.

Capa 3 — un nodo de contraexaminador LLM (LM-vs-LM)

• Un nodo separado que recibe solo la salida bajo revisión más el documento fuente (sin el contexto contaminante).
• Formula la tarea para refutar: "Intenta refutar: ¿cada afirmación en esta salida se remonta al documento fuente? Enumera las afirmaciones que no lo hacen."
• Salida {verdict, offending_claims[]}; para flujos de alto riesgo, vuelve a preguntar reordenado y toma un voto de consistencia.
• Costo: +1 llamada LLM por tarea — actívalo solo para salidas visibles al usuario o decisiones de alto riesgo.

Fase 5 — el informe

# Auditoría de alucinaciones — {agente}
## Veredicto en una línea
## Resumen de evidencia (nodos / versión auditada / muestra de tareas / muestra de correcciones + dirección)
## Hallazgos (cada uno: ubicación | R# | texto citado | consecuencia | corrección #)
## Mapa de flujo de datos y canales en punto muerto
## Recomendaciones de corrección (Capa 1/2/3, cada una etiquetada con los hallazgos que elimina)
## Por verificar (sospechas sin suficiente evidencia + cómo obtenerla)
## Límite honesto (qué correcciones son brechas de proceso, no alucinaciones; qué no cubrió esta auditoría)

La capacidad de apoyo como frontera (extensión opcional)

Fiel + relevante son el piso. El problema abierto es de apoyo: si la fuente citada apoya, contradice o se mantiene neutral sobre la afirmación. Dos notas de la investigación:

• Modélalo como postura más grado. La postura de tres vías (implicar / contradecir / neutral) se pierde el apoyo parcial o condicional, que es la mayor parte del texto regulatorio y legal. Agrega un indicador "parcial/condicional" que dirija a revisión humana.
• La capacidad de apoyo es relativa a la intención. El mismo pasaje apoya "cumplimos" y contradice "tenemos una brecha", dependiendo de lo que el usuario esté argumentando. Cuando la postura o la intención es incierta, presenta tanto una fuente de apoyo como una de contradicción y deja que el usuario elija. Presenta la dirección como un indicador que invita a la revisión, no como un veredicto.

Recordatorios

• Si un prompt es "escandalosamente malo", primero verifica si es una plantilla generada automáticamente (la repetición de Rol/Objetivo/Tarea es la pista). "Un problema sistemático con este generador" supera a enumerar la misma falla por agente.
• Contrasta dentro de un mismo agente: qué campos están limpios y cuáles fallan. La diferencia suele ser la respuesta (los campos con una opción unknown tienden a estar limpios).
• Pasa el informe por una revisión de lenguaje sencillo: un hallazgo debe ser legible para alguien que no haya leído la teoría.

---

Habilidades relacionadas

Parte de una pequeña familia de habilidades de agente abiertas para una comunicación confiable y clara:

• reduce-hallucination — audita agentes LLM; fundamenta, cita, abstente.
• better-doc — Estilo clásico + Brevedad inteligente.
• numbers — haz que los números tengan significado y muéstralos limpiamente.