sap-session

# sap-session — Evidence Loop Orchestrator ## 🎯 이 스킬의 존재 이유 대기업 SAP 환경에서는 **라이브 시스템 접근이 금지**됩니다. 그래서 AI는 실행기가 될 수 없고, 조언자에 머물 수밖에 없습니다. 이 제약을 **제거하는 대신 수용**하면서도 "조언봇"을 넘어서는 방법이 Evidence Loop입니다: - **운영자가 실행기 역할**을 맡아 SAP에서 증거를 가져오고, - **AI는 각 턴마다 가설·요청·검증·판정**을 담당하며, - **세션 상태는 파일에 저장**되어 중단·재개·인수인계가 가능합니다. 즉, Human-in-the-loop 비동기 루프입니다. 각 턴 사이에 몇 분·몇 시간·며칠이 걸려도 좋고, 다른 운영자가 이어받아도 맥락이 유지됩니다. ## 🔁 네 개의 턴 ``` ┌── Turn 1 · INTAKE ───────────────────────────────────┐ │ 운영자/엔드유저가 초기 증상 + 최소 증거를 업로드 │ │ 산출: Evidence Bundle 1개 │ │ 세션 상태: intake → hypothesizing │ └──────────────────────────────────────────────────────┘ ↓ ┌── Turn 2 · HYPOTHESIS ───────────────────────────────┐ │ AI가 2~4개 가설 + 각 가설의 반증 조건 + Follow-up │ │ Request(운영자가 다음 수집할 체크리스트) 생성 │ │ 산출: hypotheses[] + followup_request 1개 │ │ 세션 상태: hypothesizing → awaiting_evidence │ └──────────────────────────────────────────────────────┘ ↓ ┌── Turn 3 · COLLECT ──────────────────────────────────┐ │ 운영자가 Follow-up Request의 체크리스트를 SAP에서 │ │ 실행하여 새 Evidence Bundle 업로드 │ │ 산출: Evidence Bundle 1개 추가 │ │ 세션 상태: awaiting_evidence → verifying │ └──────────────────────────────────────────────────────┘ ↓ ┌── Turn 4 · VERIFY ───────────────────────────────────┐ │ AI가 새 증거로 가설을 확정/기각. 확정 시 Fix + 필수 │ │ Rollback 플랜. 기각 시 새 가설 → Turn 2 재진입. │ │ 산출: verdict 1개 │ │ 세션 상태: verifying → (resolved | hypothesizing) │ └──────────────────────────────────────────────────────┘ ``` 세부 포맷과 예시는 `references/turn-formats.md`에 있습니다. ## 📦 데이터 모델 모든 턴의 입출력은 `schemas/` 아래 5개 YAML JSON Schema로 정의됩니다: | 스키마 | 언제 생성되는가 | 어디에 저장되는가 | |---|---|---| | `evidence-bundle.schema.yaml` | Turn 1, Turn 3 | `.sapstack/sessions/{id}/bundles/evb-*.yaml` | | `hypothesis.schema.yaml` | Turn 2 | `.sapstack/sessions/{id}/hypotheses/h-*.yaml` | | `followup-request.schema.yaml` | Turn 2 | `.sapstack/sessions/{id}/requests/flr-*.yaml` | | `verdict.schema.yaml` | Turn 4 | `.sapstack/sessions/{id}/verdicts/vdc-*.yaml` | | `session-state.schema.yaml` | 매 턴 업데이트 | `.sapstack/sessions/{id}/state.yaml` | 스키마는 이 스킬의 계약(contract)이며, 모든 다른 파일(커맨드·에이전트· 웹 포털·MCP 서버)이 동일한 모양을 참조합니다. ## 🧭 AI 행동 규약 ### Universal Rules (저장소 CLAUDE.md에서 상속) 1. 회사코드·G/L 계정·원가센터·조직단위를 하드코딩 금지 2. 환경 컨텍스트(ECC/S4, on-prem/cloud, 업종)를 먼저 질문 3. ECC와 S/4HANA 동작 차이가 있으면 항상 구분 4. 모든 설정 변경은 Transport 요청 5. 프로덕션 변경 전 시뮬레이션/테스트 필수 6. SE16N으로 프로덕션 데이터 편집 제안 금지 7. 모든 액션에 T-code와 메뉴 경로 둘 다 제공 ### Session-specific Rules (이 스킬 한정) 8. **Falsifiability**: 각 가설은 반드시 `falsification_evidence`를 포함. "기각될 수 없는 가설"은 제안 불가. 9. **Rollback-or-no-Fix**: `verdict.resolutions[].fix_plan`이 존재하면 같은 resolution에 반드시 `rollback_plan`이 있어야 함. 10. **Cost-aware checks**: Follow-up Request의 각 체크는 `estimated_minutes`와 `priority` 필수. 운영자 시간을 가시화. 11. **Read-only bias**: `confirm_destructive: true`인 체크는 스키마가 거부. 모든 요청은 read-only가 기본. 12. **Audit trail**: 모든 상태 변화는 `session.audit_trail`에 append-only 기록. 삭제·수정 금지. 13. **Localization routing**: `sap_context.country_iso`가 있으면 해당 국가 컨설턴트를 자동으로 `consultant_agents_to_involve`에 포함. ## 🧰 기존 자산 오케스트레이션 이 스킬은 **새 에이전트를 만들지 않습니다**. 대신 기존 9개 컨설턴트 에이전트를 hypothesis별로 호출합니다: | 가설의 impacted_modules | 호출할 에이전트 | |---|---| | FI | `sap-fi-consultant` | | CO | `sap-co-consultant` | | MM | `sap-mm-consultant` | | SD | `sap-sd-consultant` | | PP | `sap-pp-consultant` | | PM | `sap-pm-consultant` | | QM | `sap-qm-consultant` | | WM/EWM | `sap-ewm-consultant` | | HCM | `sap-hcm-consultant` | | TR | `sap-tr-consultant` | | Cloud PE | `sap-cloud-consultant` | | ABAP | `sap-abap-developer` | | BASIS | `sap-basis-consultant` | | S4MIG | `sap-s4-migration-advisor` | | 통합/CPI/IDoc | `sap-integration-advisor` | | 신입 교육 | `sap-tutor` | 여러 모듈이 관련되면 **병렬 호출**하고, 각 에이전트의 Verdict를 종합해 최종 `verdict.resolutions[]`를 구성합니다. (Cross-module review 패턴) ## 🖥 Surfaces (세 가지 접근 경로) | Surface | 누가 | 무엇을 | |---|---|---| | **A — Operator CLI** | 운영자 | Claude Code에서 `/sap-session-*` 커맨드로 풀 Evidence Loop 진행 | | **B — Operator IDE** | 운영자 | VS Code extension 사이드바에서 세션 관리·Bundle 드래그앤드롭 (v1.6.0 실장) | | **C — End User Web** | 엔드유저 | 정적 웹 포털에서 증상 붙여넣기 → 1차 진단 → 필요시 Surface A로 에스컬레이션 | 세션은 `handoff_history`를 통해 세 표면 사이를 자유롭게 이동합니다. 엔드유저가 웹에서 시작한 세션을 운영자가 CLI로 이어받는 것이 대표 시나리오입니다. ## 📝 Turn-aware 응답 포맷 Evidence Loop 모드에서는 기존 Standard Response Format (Issue → Root Cause → Check → Fix → Prevention → Note) 대신 Turn-aware 포맷을 사용합니다: - **Turn 1 (Intake)**: `초기 증상 요약 + 매칭된 symptom-index + sap_context 질문` - **Turn 2 (Hypothesis)**: `현재 증거 요약 + 2-4개 가설 카드 + follow-up 체크리스트` - **Turn 3 (Collect)**: (AI는 말하지 않음. 운영자 액션 턴.) - **Turn 4 (Verify)**: `가설별 판정 + 확정 가설의 Fix/Rollback/Prevention` 단순 질의(예: "FB01이 뭔가요?")는 기존 Standard Response Format을 유지합니다. **CLAUDE.md 옵션 B(병행 모드)** 참조. ## 🚀 Quick Start ```bash # 새 세션 시작 (Surface A — CLI) /sap-session-start "F110 Proposal 실패 — 벤더 100234" # 초기 Bundle 업로드 /sap-session-add-evidence sess-20260411-m2p9xt ./f110-log.txt ./lfb1-dump.csv # 다음 턴 실행 (AI가 Hypothesis turn 수행) /sap-session-next-turn sess-20260411-m2p9xt # 운영자가 SAP에서 후속 증거 수집 후 다시 add-evidence /sap-session-add-evidence sess-20260411-m2p9xt ./vendor-bank-info.csv # Verify 턴 /sap-session-next-turn sess-20260411-m2p9xt # 다른 surface로 넘기기 /sap-session-handoff sess-20260411-m2p9xt --to web_triage --reason "end-user 재연 확인 필요" ``` ## 📚 참조 - `references/turn-formats.md` — 각 턴의 상세 입출력 포맷과 예시 - `references/evidence-bundle-guide.md` — 운영자가 Bundle을 준비할 때 주의점 - `references/followup-authoring.md` — AI가 Follow-up을 작성할 때 품질 기준 - `references/session-state-lifecycle.md` — 세션 상태 전이와 재개 규약 - `references/korean-field-language.md` — 한국 SAP 현장체 작성 규약 (Slice 8) - `../../../schemas/` — 5개 JSON Schema (계약 정의) - `../../../data/synonyms.yaml` — 58 용어 + 10 약어 + 15 업무 시점 동의어 사전 - `../../../CLAUDE.md` — Universal Rules (#8 현장체 원칙 포함) + 응답 포맷 ## ⚠️ 명시적 비목표 - **라이브 SAP 연결 안 함**. RFC·OData·Fiori 직접 호출 없음. - **프로덕션 데이터 편집 지시 안 함**. 모든 Fix는 운영자가 수동 실행. - **자동 Transport 이동 안 함**. Transport는 언제나 사람의 승인. - **엔드유저 CLI 사용 강제 안 함**. Surface C(웹)가 엔드유저의 기본 경로. ## 🧪 성숙도 **v0.1.0 — experimental**. 첫 dog-food 케이스는 `/sap-session` Slice 2에서 F110 지급실행 실패 시나리오로 검증합니다. 실제 케이스 3건 이상 통과 후 stage를 `stable`로 승격합니다.