docs: IntentAnalyzer 미사용 문제 트러블슈팅 추가

- 멘션 필수 UX 문제
- 자연어 명령 인식 실패
- 고아 코드 상태 분석

troubleshooting/250914_happybell80_IntentAnalyzer_미사용_문제.md

@@ -0,0 +1,78 @@
+# 트러블슈팅: IntentAnalyzer 미사용 및 Slack UX 문제
+
+## 발생 시간
+- 2025년 9월 14일
+
+## 문제 상황
+1. **멘션 필수 문제**: 채널에서 항상 `@robeing /search` 형태로 멘션 필요
+2. **자연어 인식 실패**: "검색해줘", "찾아봐" 같은 자연어 명령 무시
+3. **마크다운 포맷 깨짐**: `**굵게**` 형식이 Slack에서 깨짐 (Slack은 `*굵게*` 사용)
+
+## 원인 분석
+
+### 1. IntentAnalyzer 고아 코드 상태
+```python
+# app/llm/intent_analyzer.py 존재하지만 미사용
+- "검색해줘" → "/search" 변환 기능 구현됨
+- 어디서도 import/호출하지 않음
+- slack_handler.py:81에서 router.route_message() 직접 호출
+```
+
+### 2. Slack 이벤트 처리 로직
+```python
+# slack_handler.py:209
+if event_type == "app_mention" or (event_type == "message" and is_dm):
+    # 채널 메시지는 멘션 필수, DM만 멘션 없이 가능
+```
+
+### 3. 응답 포맷 문제
+- LLM이 `**굵게**` 마크다운 생성
+- Slack mrkdwn은 `*굵게*` 형식만 지원
+
+## 해결 방법
+
+### 1. IntentAnalyzer 연결
+```python
+# slack_handler.py 수정
+from app.llm.intent_analyzer import IntentAnalyzer
+
+async def process_slack_message_async(text: str, user_id: str, context: dict):
+    # ... 기존 코드 ...
+
+    # Line 78-81 사이에 추가
+    analyzer = IntentAnalyzer()
+    analyzed = await analyzer.analyze_user_intent(text, handler)
+    if analyzed != text:
+        logger.info(f"Intent converted: '{text}' → '{analyzed}'")
+        text = analyzed
+
+    # 기존 router 호출
+    result = await router.route_message(text, user_id, channel, thread_ts)
+```
+
+### 2. 채널 메시지 키워드 감지
+```python
+# slack_handler.py:209 수정
+search_keywords = ["검색", "찾아", "알아봐", "서치"]
+is_search_request = any(kw in text for kw in search_keywords)
+
+if event_type == "app_mention" or (event_type == "message" and is_dm) or is_search_request:
+    # 검색 키워드 포함 시 멘션 없이도 처리
+```
+
+### 3. 응답 포맷 변환
+```python
+# slack_handler.py:90 근처
+content = result.get("content", "")
+content = content.replace("**", "*")  # Slack 포맷 변환
+```
+
+## 교훈
+1. **기능 구현 != 기능 활성화**: 코드 작성 후 연결 확인 필수
+2. **고아 코드 점검**: 미사용 모듈 정기적 확인
+3. **플랫폼별 포맷**: Slack mrkdwn ≠ Markdown
+
+## 영향 범위
+- 모든 Slack 사용자의 검색 기능 UX 개선
+- 자연어 명령 지원으로 사용성 향상
+- 포맷 깨짐 문제 해결로 가독성 개선