docs: add rb8001 calendar intent overlap plan

journey/plans/251209_rb8001_calendar_intent_overlap_plan.md

@@ -0,0 +1,82 @@
+# rb8001 캘린더 조회/생성 의도 경계 세부 설계
+
+**날짜**: 2025-12-09
+**목표**: calendar_query vs calendar_event 경계 케이스를 UX/TDD 기준으로 명확히 정의하고, 3단계 의도 아키텍처와 일관되게 구현한다.
+
+---
+
+## 1. 현재 상태 정리
+
+- FastPath 정규식이 `calendar_query`를 `calendar_event`보다 우선 매칭하여, 조회·생성이 섞인 문장도 대부분 `calendar_query`로 고정됨.  
+  - 의도 패턴: `rb8001/app/services/brain/decision_engine.py:120-180`
+- 3단계 의도 파이프라인(Goal → ActionPlan → SkillSequence)은 도입되었지만, 캘린더 조회/생성 경계에는 아직 적극적으로 사용되지 않음.  
+  - 메타데이터 파이프라인: `rb8001/app/services/brain/decision_engine.py:540-629`
+- 기존 캘린더 테스트는 조회 vs 생성 분리, all-day 파싱, 승인 플로우에 초점.  
+  - 조회 vs 생성 TDD: `rb8001/tests/test_calendar_query_vs_create.py:1-220`  
+  - 로그 기반 시나리오: `rb8001/tests/test_intent_scenarios_from_logs.py:1-220`  
+  - 겹침 케이스 실험 스크립트: `rb8001/tests/test_calendar_intent_overlap_cases.py:1-80`
+
+---
+
+## 2. UX/의도 기준
+
+- **조회 중심 문장**: "등록돼 있는지 확인", "일정 전체 확인", "스케줄 보여줘" → 기본 intent는 `calendar_query`.  
+- **생성 중심 문장**: "일정 등록해줘/잡아줘/넣어줘" + 날짜·시간·타이틀 정보가 충분 → 기본 intent는 `calendar_event`.  
+- **조회+생성 혼합 문장**: "있나 확인하고, 없으면 잡아줘", "필요하면 등록해줘" → 단일 intent로 강제하지 않고, ① 조회 → ② 조건부 생성 멀티 액션으로 다룬다.  
+- UX 원칙: 애매하면 조용히 잘못 실행하지 말고, 한 번 더 물어보는 clarify를 사용한다.
+
+---
+
+## 3. 설계 방향
+
+### 3.1 FastPath 의도 판정 조정
+
+- 조회/생성 정규식이 **동시에 매칭**되는 경우를 감지한다.  
+- 이 경우 FastPath에서 바로 `calendar_query` 또는 `calendar_event`로 확정하지 않고, 상위 카테고리(예: `SCHEDULE_MANAGEMENT`) + 낮은 confidence로 내려 보낸다.  
+- `"없으면 잡아줘"`, `"필요하면 등록해줘"` 등 조건부 생성 패턴은 별도 플래그로 표시하여 후속 단계에서 ActionPlan에 반영한다.
+
+### 3.2 3단계 파이프라인 활용
+
+- IntentAnalyzer/ActionPlanner에서 조회+생성 혼합 메시지를 **Goal: SCHEDULE_MANAGEMENT**로 해석한다.  
+- ActionPlanner는 플래그/슬롯을 기준으로 다음 두 가지 플랜을 만든다.  
+  - Plan A: `[QUERY_CALENDAR]` (조회만)  
+  - Plan B: `[QUERY_CALENDAR, CONDITIONAL_CREATE_EVENT]` (없으면 등록)  
+- SkillSelector는 Plan B에 대해 `CALENDAR.get_events` 후, 결과가 비어 있을 때만 `CALENDAR.create_event`를 실행하는 시퀀스를 생성한다.
+
+### 3.3 Clarify·승인 흐름
+
+- FastPath/IntentAnalyzer에서 의도 불확실(conf 낮거나 혼합)하면, LLM 기반 clarify 메시지를 생성한다.  
+- 예: "먼저 내일 일정이 등록돼 있는지 확인하고, 없으면 일정까지 등록해드릴까요?"  
+- 사용자가 "응/ㅇㅇ/그래" 등으로 승인하면 `calendar_approval`이 원래 Plan A/B를 기억한 상태에서 적절한 액션을 선택하도록 한다.
+
+---
+
+## 4. 작업 항목 (하위 설계)
+
+1. **의도 패턴/슬롯 확장**  
+   - 조회/생성 동시 매칭, `"없으면 잡아줘"`, `"필요하면 등록해줘"` 등을 감지하는 보조 패턴/슬롯 추가.  
+   - 위치: `rb8001/app/services/brain/decision_engine.py` 및 `app/services/brain/intent` 하위 모듈.
+2. **FastPath 의사결정 로직 개선**  
+   - `analyze_intent()`에서 캘린더 혼합 문장에 대해 단일 intent 강제 대신 상위 카테고리 + 플래그 반환.
+3. **ActionPlanner 확장**  
+   - `ActionPlanner.plan()`에서 SCHEDULE_MANAGEMENT + 플래그를 입력받아 `[QUERY]` vs `[QUERY→CONDITIONAL_CREATE]`를 구분.  
+   - 위치: `rb8001/app/services/brain/intent/action_planner.py`.
+4. **SkillSelector 멀티 액션 시퀀스**  
+   - `SkillSelector.select()`에서 CONDITIONAL_CREATE_EVENT를 지원하고, get_events 결과에 따라 create_event 실행 여부를 결정.  
+   - 위치: `rb8001/app/services/brain/intent/skill_selector.py`.
+5. **calendar_approval 행동 분기**  
+   - `DecisionEngine.decide_skill_sequence()` 또는 intent 파이프라인에서 `calendar_approval`이 직전 Plan A/B를 기억하도록 메타데이터 연결.  
+6. **의도 경계 TDD 케이스 추가**  
+   - 위 10개 문장을 포함해 `"등록돼 있는지 확인"`, `"없으면 잡아줘"` 패턴을 `test_calendar_query_vs_create.py`, `test_intent_scenarios_from_logs.py`에 기대 intent/액션으로 고정.  
+7. **리뷰 큐 연동 규칙**  
+   - calendar_query vs calendar_event margin이 작거나, 사용자 피드백(wrong/down)이 붙은 캘린더 케이스를 IntentReviewQueue에 자동 적재.  
+   - 위치: `rb8001/app/services/brain/intent_review.py`, `app/state/conversation_repository.py`.
+
+---
+
+## 5. 검증·운영
+
+- `pytest rb8001/tests/test_calendar_query_vs_create.py rb8001/tests/test_intent_scenarios_from_logs.py`로 회귀 여부를 상시 확인한다.  
+- 관리자용 Intent 리뷰 화면에서 캘린더 관련 샘플을 필터링하여, 조회↔생성 경계 오류를 집중 라벨링한다.  
+- 일정 기간 운영 후, 리뷰 큐/로그 데이터를 기반으로 FastPath 정규식·threshold를 재튜닝하고 이 계획 문서를 `troubleshooting/` 문서로 승격한다.
+