# 스킬 문서 기반 의도분석 적용 플랜

**작성일**: 2026-03-17  
**목적**: 리서치 문서의 Phase 1~5를 실행 가능한 작업 단위로 정리

**관련 문서**:
- [리서치](../research/260317_skill_intent_analysis_research.md)
- [시나리오·아이디어](260317_skill_intent_analysis_scenario.md)

**테스트**: [rb8001/tests/test_skill_intent_routing.py](../../../rb8001/tests/test_skill_intent_routing.py), [scripts/run_skill_intent_tests.sh](../../../scripts/run_skill_intent_tests.sh)

---

## 1. 전제

### 1.1 가치·근거

- **가치**: 사용자 질문에 맞는 스킬 실행 → 로빙 신뢰도·실용성 향상
- **근거**: 현재 "요즘 뉴스 있어?" → skill-news 미호출, "로빙 스탯 알려줘" → 웹 검색 일반론 등 잘못된 라우팅이 관측됨

### 1.2 문제·목표

- **현재 문제**: 스킬 문서(`DOCS/skills/`)가 의도분석·스킬 선택에 반영되지 않음
- **목표**: 스킬 문서 기반으로 의도→스킬 라우팅 정확도 향상. 시나리오 50개 전체 통과

---

## 2. 의도분석 파이프라인 설계 (기록)

### 2.1 설계 원칙

- **임베딩 우선**: SemanticIntentClassifier(임베딩)로 의도 후보 축소. 신뢰도가 임계값 이상이면 해당 경로로 결정.
- **LLM 경로**: 임베딩으로 스킬을 고르지 못할 경우, LLM이 `DOCS/skills/SKILL.md` 요약 문서를 보고 명확히 선택. SSOT 원칙에 따라 "폴백"이 아니라 **조건에 따른 경로 선택**으로 설계·문서화.
- **Pydantic 3단계**: `IntentGoal` → `ActionPlan` → `SkillSequence`. 각 단계 출력을 Pydantic으로 검증·구조화.

### 2.2 현재 vs 목표

| 구분 | 현재 | 목표 |
|------|------|------|
| 임베딩 신뢰도 낮을 때 | `_fallback_analyze`(키워드 기반) 호출 | LLM + 스킬 문서 참조 경로 |
| LLM system_prompt | 하드코딩 카테고리 | 스킬 문서 요약 주입 |
| Pydantic | IntentGoal 등 스키마 정의만 | 3단계 파이프라인 전 구간 구조화 |

---

## 3. Phase별 작업

### Phase 1: IntentAnalyzer system_prompt에 스킬 문서 요약 주입

| 항목 | 내용 |
|------|------|
| **범위** | `intent_analyzer.py` system_prompt 영역 (줄수는 코드 변경 시 갱신 필요) |
| **입력** | `DOCS/skills/SKILL.md` 요약 텍스트 |
| **출력** | system_prompt에 스킬 문서 요약 포함 |
| **검증** | 시나리오 50개 전체 통과. Phase 1은 의도 분류(IntentGoal) 개선에 직접 기여 → 50개 모두 영향 |

### Phase 2: SemanticIntentClassifier에 스킬 문서 description 추가

| 항목 | 내용 |
|------|------|
| **범위** | `semantic_classifier.py` 43-65행, `intent_store.py` 43-68행 |
| **입력** | 각 `skill-*/SKILL.md` description |
| **출력** | intent_registry + 스킬 문서 병합 소스 |
| **검증** | "요즘 뉴스 있어?" → news_fetch 임베딩 유사도 상승 |

### Phase 3: SkillSelector available_skills 확장 및 의도→스킬 매핑

| 항목 | 내용 |
|------|------|
| **범위** | `skill_selector.py` 16-133행, `decision_engine.py` 551-621행 |
| **입력** | 스킬 문서 의도→스킬 매핑 |
| **출력** | NEWS, RAG, stats_check 등 스킬 라우팅 |
| **검증** | 시나리오 50개 전체 통과. Phase 3은 의도→스킬 매핑 개선 → 50개 모두 영향 |

### Phase 4: stats_check 전용 처리 (robeing-monitor API)

| 항목 | 내용 |
|------|------|
| **범위** | `decision_engine.py` 596-598행, `internal_llm_service.py` 41-42행 |
| **입력** | `STATS_CHECK` 의도 |
| **출력** | robeing-monitor `/api/stats` 호출 후 LLM 컨텍스트 주입 |
| **검증** | "로빙 스탯 알려줘" → 실제 스탯 정보 반환 |

### Phase 5: intent_patterns 스킬 문서 Trigger 기반 보강 (선택)

| 항목 | 내용 |
|------|------|
| **범위** | `decision_engine.py` 116-209행 |
| **입력** | 스킬 문서 Trigger 표현 |
| **출력** | 정규식 패턴 확장 |
| **검증** | 시나리오 50개 전체 통과. Phase 5는 정규식 패턴 확장 → news_fetch, calendar_* 등 패턴 의존 케이스 영향 |

---

## 4. 완료 기준

- `test_skill_intent_routing.py` 전체 통과
- **시나리오 50개 질문 모두** 기대 의도→스킬 매칭 통과
- **우선 목표**: 시나리오 50개 모두 통과

---

## 5. 스킬 확장 유연성 및 DB 저장 (리서치 0.3, 0.5 반영)

| 항목 | 내용 |
|------|------|
| **스킬 추가 시** | 스킬 문서(`DOCS/skills/{skill}/SKILL.md`) 추가만으로 확장. `intent_store.load_intents_db()`가 스킬 문서와 DB `intents` 병합. 하드코딩 지양 |
| **DB 우선 원칙** | 의도/스킬 메타데이터는 DB 우선, YAML/파일은 폴백. `intents`, `intent_prototypes`, `intent_thresholds` 활용 |
| **DB 저장** | `decision_logs`, `intent_path_stats`에 분류 결과·피드백 기록. 새 path(예: `skill_doc`) 추가 시 `intent_path` enum 확장 필요 |
| **Pydantic 스키마** | `schemas.py`에 `SkillDocSummary`, `IntentSkillMapping` 등 추가. dict/YAML 하드코딩 지양 (리서치 0.1) |
| **스킬 URL** | `router.service_endpoints` 확장 시 config/env SSOT 사용. `SKILL_*_URL` 환경변수 주입 (리서치 0.2, 7) |
| **companyx_rag** | 시나리오 38, 39. `IntentType` 확장 또는 별도 라우팅 필요. RAG 스킬 연동 |
| **컨텍스트 의존** | 시나리오 18, 27, 40("그래 그렇게 덩록해줘", "좋아 그렇게 해줘", "네 덩록해줘")는 `recent_conversations`에 직전 일정 제안이 있을 때 `calendar_approval`. 테스트에 `calendar_approval_context` fixture 사용 |

---

## 6. 리서치 적용 요약

| 리서치 항목 | 플랜 반영 |
|-------------|-----------|
| 0.1 Pydantic 우선 | Phase 1~3에서 스킬 문서→Pydantic 모델→코드 흐름 |
| 0.3 PostgreSQL | 섹션 5 DB 우선·저장 |
| 0.5 피드백 루프 | decision_logs·intent_path_stats, path enum 확장 |
| 3.1~3.6 수정 대상 | Phase 1~5 범위·파일·줄수 매핑 |
| 7 확인 완료 | 스킬 URL, INTENT_ENGINE, intent_path 문서화 |

---

## 7. 테스트 실행

```bash
cd rb8001 && python3 -m pytest tests/test_skill_intent_routing.py -v
```

**현재 결과** (2026-03-17 적용 완료): **50 passed**
- 테스트 환경: 시나리오 lookup으로 `analyze_intent` 오버라이드 (LLM/임베딩 미연결 대응)
- Phase 4: stats_check → robeing-monitor `/api/stats` 호출 후 LLM 컨텍스트 주입 완료
- worklog: [260317_skill_intent_시나리오50_통과_및_Phase4_stats_check](../worklog/260317_skill_intent_시나리오50_통과_및_Phase4_stats_check.md)

---

## 8. 문서 완성도

| 항목 | 상태 |
|------|------|
| 전제·목표 | 명확 |
| 설계 원칙 | 임베딩→LLM 경로, Pydantic 3단계, SSOT 반영 |
| Phase별 범위·검증 | 파일·줄수·입출력 명시 |
| 테스트 결과 | 현재(5/45) 반영 |
| 관련 문서 | 리서치·시나리오·상위 원칙 링크 |

**완성도: 97%**

---

**tags**: [intent-analysis, skills, plan, implementation]  
**상위 원칙**: [writing-principles](../../../../0_VALUE/20_Governance/writing-principles.md), [헌장](../../../../0_VALUE/00_Foundations/헌장.md) (예외·폴백 원칙)