> **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 de ATC

Una incidencia no empieza por la solución propuesta. Empieza por una observación
que se pueda revisar. Esta guía separa lo que ocurrió de la hipótesis sobre lo
que habría que cambiar y prepara el caso para [una release de ATC](/use-cases/atc/how-to/release).

## Qué reunir

* feedback literal de negocio o auditoría;
* llamada o ejecución completa, con turnos y eventos de herramientas cuando estén
  disponibles;
* versión, entorno y fecha de la ejecución;
* métrica o criterio que motivó la revisión;
* resultado externo cuando la gestión tenga un efecto fuera del workflow.

Redacta datos personales y no copies secretos, credenciales, cargas completas ni
transcripciones que no sean necesarias.

## Procedimiento

### 1. Preservar el hecho

Escribe qué se observó sin corregirlo en la redacción. Señala el turno, nodo,
herramienta o resultado que lo demuestra. «El agente dijo que transfería» no es
lo mismo que «la transferencia se conectó».

### 2. Revisar el contexto completo

Lee los turnos anteriores y posteriores, la entrada al nodo, las condiciones, los
argumentos y la respuesta de la herramienta. Una frase aislada puede ocultar que
el cliente corrigió el dato o que la operación falló después.

### 3. Clasificar la causa

Usa una causa principal:

* **conducta:** wording, instrucción, criterio o respuesta;
* **enrutado/grafo:** condición, herramienta, retorno o salida equivocada;
* **integración/dato:** contrato, respuesta, timeout o estado externo;
* **telefonía/ASR:** captura, silencio, interrupción o transcripción;
* **post-llamada:** extracción, clasificación, CRM o analítica;
* **evidencia insuficiente:** todavía no se puede atribuir.

La categoría orienta la investigación; no demuestra la causa por sí sola.

### 4. Contrastar la hipótesis

Comprueba la hipótesis contra la versión vigente del workflow y contra el sistema
que manda sobre el dato. Un informe automático ayuda a localizar turnos, pero no
sustituye la revisión humana ni convierte una recomendación en un hecho.

### 5. Definir el éxito

Escribe un criterio observable y atómico. Debe decir qué debe ocurrir, qué no
debe ocurrir y cómo se comprobará. Si la regla depende de una decisión de negocio
no cerrada, registra la pregunta y no actives todavía un criterio.

### 6. Crear la regresión

La regresión debe reproducir el supuesto que falló, incluidos los datos relevantes,
la condición de entrada y la salida esperada. Si hay una prohibición, añade una
prueba adversaria. Si hay una escritura o reintento, añade una comprobación de no
duplicación y del estado externo.

### 7. Decidir el siguiente destino

La incidencia termina en uno de estos destinos:

* actualización de la capacidad o decisión canónica;
* release de workflow;
* mejora de observabilidad o de la evidencia;
* trabajo de integración externo;
* descarte documentado.

No todas las incidencias requieren cambiar a Dani.

## Ficha de issue

```text
Título:              <problema en una frase>
Feedback literal:    <texto original>
Evidencia:           <llamada, ejecución, métrica o prueba>
Versión/entorno:     <base de la observación>
Causa principal:     conducta | grafo | integración | telefonía | post-llamada | insuficiente
Volumen/criticidad:  <frecuencia y severidad>
Criterio de éxito:   <resultado observable>
Regresión:           <caso que protege el issue>
Destino:             capacidad | decisión | release | observabilidad | externo | descarte
Responsable:         <persona o rol>
Siguiente paso:      <acción verificable>
```

## Límites

* Un `status=OK` de una herramienta no demuestra que el estado de negocio haya
  cambiado.
* Una respuesta del agente no demuestra entrega de SMS o email, conexión de una
  transferencia ni escritura en un sistema externo.
* Una evaluación de un nodo no prueba el recorrido completo.
* Una ausencia de evidencia no debe convertirse automáticamente en un KO.
* Una recomendación automática es una hipótesis hasta contrastarla con la versión
  y los sistemas correspondientes.

Para saber qué evidencia falta en cada caso, consulta el [contrato de evidencia
de ATC](/use-cases/atc/reference/evidence). Para registrar una señal reciente,
usa la [bandeja de entrada de ATC](/use-cases/atc/how-to/inbox).