> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Diagnosticar una incidencia

Empieza por clasificar la frontera que falla: entrada, persistencia, consola,
asignación, webhook, señal o backend de negocio. No corrijas reintentando a
ciegas ni cambies un workflow live para confirmar una hipótesis.

## Tabla rápida

| Síntoma | Comprobación segura | Posible causa |
|---|---|---|
| No aparece el ticket | Estado HTTP, correlación, entorno y respuesta de idempotencia | Credencial, schema, target o Twin. |
| Hay dos tickets | Comparar identificador externo y momento de creación | Reintento sin idempotencia. |
| Hay ticket sin histórico | Revisar creación por etapas y tamaño permitido | Payload incompleto o histórico rechazado. |
| Respuesta no llega al cliente | Comprobar mensaje guardado, webhook y entrega del workflow | Webhook, canal o sesión finalizada. |
| Nota privada sale fuera | Revisar tipo de mensaje y filtro del webhook | Error de clasificación o contrato. |
| Caso se cierra solo | Revisar actor, evento y `close_reason` | Regla antigua, job o entorno equivocado. |
| Caso no pasa a Pendientes | Revisar quién habló último, umbral y consola abierta | Condición de inactividad o polling. |
| Caso no vuelve a la cola | Revisar disponibilidad, barrido y asignación | Horario, pausa, vacaciones o capacidad. |
| Señal no cambia el workflow | Revisar sesión, entorno y permisos de señal | Correlación o credencial de señal. |
| Agente ve demasiado | Probar rol y respuesta server-side | Filtro de autorización incompleto. |
| Omega no aparece | Comprobar identificador de cuenta autorizado | La ingesta no lo recibió; no inferirlo. |

## Orden de diagnóstico

1. Captura ticket, `session_id`, correlación, entorno y hora aproximada.
2. Comprueba si la operación se ejecutó una vez o varias.
3. Consulta el estado por la API autorizada antes de reenviar.
4. Revisa logs redactados: método, ruta lógica, status y latencia.
5. Separa fallo de TeLeo, HappyRobot, webhook y backend de negocio.
6. Reproduce con fixture sintético en el mismo entorno.
7. Aplica fallback y escala al owner si el efecto afecta al cliente.

Nunca pegues en un ticket de soporte una API key, cookie, Bearer token,
transcript completo, DNI, IBAN, teléfono completo o enlace privado de plataforma.

## Señales de datos inconsistentes

Detén la mutación y solicita revisión si:

* el ticket apunta a un entorno distinto al de la sesión;
* el identificador externo cambia durante una conversación;
* la respuesta del backend contradice el estado del ticket;
* el mismo `message_id` tiene dos cuerpos;
* una nota no tiene clasificación pública/privada;
* una señal se publica con otro entorno;
* la UI muestra permiso que la API no confirma.

## Cierre de la incidencia

Documenta causa, alcance, tickets afectados sin PII, workaround, owner,
corrección, prueba de regresión y condición de rollback. Separa la release de la
app, la del workflow y la de esta documentación.