> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# 실패 진단

> 틀린 답을 만든 Flow의 그 스텝을 콕 짚어냅니다

실패를 고치려면 먼저 어디서 어긋났는지 알아야 합니다. Nora의 Diagnose는 실패한 트레이스를 되짚어, 문제를 만든 특정 스텝이나 리트리벌, 프롬프트, 도구를 짚어냅니다.

## Diagnose 돌리기

클러스터를 열면 자동으로 돕니다. **Cluster → Diagnose**가 페이지에 들어서는 순간 실행됩니다.

신호 하나에서도 쓸 수 있습니다(**Signal → Diagnose**). 개선으로 올리기 전에 일회성으로 살펴볼 때 좋습니다.

## 진단 카테고리

Diagnose는 각 실패를 다음 중 하나 이상으로 분류합니다.

* **리트리벌 이슈** 맞는 청크가 top K에 없었습니다. 진단이 실패 패턴과 맞아떨어집니다.
* **그라운딩 이슈** 가져온 청크가 오래됐거나, 그래프와 어긋나거나, 인용이 빠졌습니다.
* **프롬프트 이슈** 프롬프트가 꼭 필요한 동작을 분명히 짚어 주지 않았습니다.
* **도구 이슈** 도구가 안 불렸거나, 잘못 불렸거나, 틀린 데이터를 돌려줬습니다.
* **메모리 이슈** Agent가 이 스코프에서 오래됐거나 없는 메모리를 들고 있습니다.
* **모델 이슈** 모델이 그냥 틀립니다(대개 클러스터의 어려운 케이스가 같은 패턴으로 반복될 때 드러납니다).
* **데이터 이슈** 필요한 정보가 지식 베이스에 아예 없습니다.

원인이 여럿인 실패도 있습니다. Diagnose가 가능성 순으로 매깁니다.

## 진단 근거

가설로 세운 원인마다 Diagnose가 이렇게 보여줍니다.

* 클러스터의 어느 트레이스가 이 가설을 뒷받침하는지.
* 각 트레이스의 어느 스텝이 걸렸는지.
* 신뢰 점수.

근거 줄을 누르면 트레이스로 건너뛰어 맥락 속에서 문제를 봅니다.

## 근본 원인 노트

Diagnose 끝에 Nora가 **근본 원인 노트**를 씁니다. 사람이 읽을 한 단락짜리 요약이죠. 이런 식입니다.

> **근본 원인**: 리트리벌 미스. 실패한 트레이스 10개 중 8개에서, 고객에게 보여줄 환불 정책 청크가 top-K 결과에 없었습니다. 청크는 멀쩡히 있는데 키워드 점수가 낮아 12\~15위에 밀려 있습니다(쿼리는 "money back" 을 쓰는데 청크는 "refund" 를 씁니다).

사람이 가장 먼저 읽는 게 이 노트입니다. 개선 플로우가 제안을 만들 때 쓰는 것도 이 노트고요.

## 진단 뒤집기

Nora의 진단에 동의하지 않으면 **Suggest different root cause**를 눌러 메뉴에서 고르거나 직접 적습니다. 이렇게 바로잡은 내용이 제안 생성에 반영됩니다.

흔히 뒤집는 이유는 이렇습니다.

* Diagnose는 리트리벌 탓을 했는데, 소스 문서가 오래됐다는 걸 여러분이 아는 경우(데이터 이슈).
* Diagnose는 프롬프트 탓을 했는데, 도구 설정이 틀렸다는 걸 여러분이 아는 경우(도구 이슈).

## 근본 원인이 여럿일 때

정말로 원인이 섞인 클러스터도 있습니다. Diagnose가 이를 "primary + secondary 근본 원인" 으로 나눠 짚고 각각에 제안을 만듭니다.

흔한 형태는 primary가 프롬프트 이슈, secondary가 리트리벌 이슈인 경우입니다. 둘 다 고쳐야 하지만 보통 primary를 먼저 잡습니다.

## 진단 이력

Diagnose 실행은 클러스터마다 캐시됩니다. 지난 실행 뒤로 새 신호가 없으면 다시 돌려도 결과가 같습니다.

이럴 때 손수 다시 진단하세요.

* 클러스터에 새 신호가 합류했을 때.
* 분석을 바꿀 만한 지식을 새로 넣었을 때.
* 관련 설정(리트리벌 프리셋, 프롬프트 등)을 바꾼 뒤 진단이 달라지는지 보고 싶을 때.

## Diagnose가 못 짚을 때

가끔 Diagnose가 "모르겠다" 고 합니다. 실패 트레이스들이 고칠 수 있는 원인으로 이어지는 공통점을 안 가진 경우죠. 그럴 땐 이렇습니다.

* 클러스터가 너무 잡다한 것일 수 있습니다. 나누는 걸 생각해 보세요.
* 아니면 근본 원인이 바깥에 있습니다(상류 API 변경, 모델 제공자 업데이트). 직접 조사하세요.

Nora는 이를 "no confident root cause" 노트로 띄우고, 개선 플로우도 제안을 자동으로 만들지 않습니다.