From 10eef11c97a1e25d3e98bcd41a5b88d7b92c992d Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Thu, 23 Oct 2025 13:21:07 +0900
Subject: [PATCH] =?UTF-8?q?docs(troubleshooting):=20=EC=9B=B9=EA=B2=80?=
 =?UTF-8?q?=EC=83=89=20=EC=97=94=ED=8B=B0=ED=8B=B0=20=ED=99=95=EC=A0=95?=
 =?UTF-8?q?=C2=B7=EC=A0=95=ED=99=95=EB=8F=84=20=EA=B0=9C=EC=84=A0=20?=
 =?UTF-8?q?=EC=84=A4=EA=B3=84/=EC=A0=81=EC=9A=A9=20=EC=A0=95=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...01_웹검색_엔티티_정확도_개선.md | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 troubleshooting/251023_admin_rb8001_웹검색_엔티티_정확도_개선.md

diff --git a/troubleshooting/251023_admin_rb8001_웹검색_엔티티_정확도_개선.md b/troubleshooting/251023_admin_rb8001_웹검색_엔티티_정확도_개선.md
new file mode 100644
index 0000000..f0807ec
--- /dev/null
+++ b/troubleshooting/251023_admin_rb8001_웹검색_엔티티_정확도_개선.md
@@ -0,0 +1,42 @@
+# rb8001: 웹검색 엔티티 확정·정확도 개선 설계/적용
+
+**날짜**: 2025-10-23  
+**작성자**: admin  
+**관련 파일**: `app/router/message_router.py`, `app/router/slack_handler.py`, `app/services/workflows/web_search_workflow.py`, `app/brain/decision_engine.py`
+
+---
+
+## 문제 요약 (로그 근거 포함)
+- “이 기업 …” 질의가 오래된 기억/파일명 상수(CODE_OF_CONDUCT 등)에 끌려가 잘못된 엔티티로 검색/요약됨.  
+- LangGraph 경로 예외로 폴백(/search)로 자주 떨어져 대명사 해소·CQR·rerank 미실행, LLM 기본응답 반복.
+- 대표/이름 질의가 엔티티 미확정 상태에서 실행되어 잘못된 대상에 대한 답변 반복.
+
+## 해결 설계/적용
+1) 그래프 파이프 강화  
+   - resolve(코리퍼런스) → link(엔티티링크/신뢰도) → CQR(재작성) → search → rerank → summarize → format.  
+   - AsyncSqliteSaver(체크포인터) + thread_id/checkpoint_ns 지정, 실패 시 폴백 로깅.
+
+2) 폴백 경로 동등 정책  
+   - /search 경로에서도 대명사 해소 스코어링(한글/기업접미사 가중, 파일·상수 패널티) 적용.  
+   - 저신뢰(<2) 또는 미해결 시 즉시 재질문(clarify) 반환.
+
+3) Clarify UX  
+   - Slack 버튼으로 후보(최대 3) 제시 → 선택 즉시 재검색/응답.
+
+4) 라우팅 보강  
+   - “(기업|회사).*(이름|대표|대표이사)” 등도 웹검색 파이프로 라우팅.
+
+## 정확도/표현
+- 확신도 낮은 경우: “재질문/보류(출처 부족)”로 응답.  
+- 요약/포맷: ‘출처:’ 블록에 상위 3개 제목+URL 표준 표기.
+
+## 검증/모니터링
+- 테스트(로컬): 엔티티 우선순위·clarify·그래프 경로 안정화 검증.  
+- 로그: `[WebSearch] CAND entity`, `Pronoun resolved`, `Fallback /search`, Clarify 버튼 액션 로그.  
+- 지표: 성공률·clarify 비율·폴백 비율·응답 확신도(ECE/Brier).
+
+## 교훈
+- 엔티티 미확정 상태의 실행 금지, 재질문→확정→실행으로 느린 경로라도 안정성 우선.  
+- 오래된 기억/파일 토큰은 강한 패널티, 최신/한글 기업명·기업 접미사 가중으로 현실적 후보를 우선.
+
+---