diff --git a/issue-1501-analysis.md b/issue-1501-analysis.md deleted file mode 100644 index 52295a94..00000000 --- a/issue-1501-analysis.md +++ /dev/null @@ -1,357 +0,0 @@ -# Issue #1501 분석 보고서: ULW Mode PLAN AGENT 무한루프 - -## 📋 이슈 요약 - -**증상:** -- ULW (ultrawork) mode에서 PLAN AGENT가 무한루프에 빠짐 -- 분석/탐색 완료 후 plan만 계속 생성 -- 1분마다 매우 작은 토큰으로 요청 발생 - -**예상 동작:** -- 탐색 완료 후 solution document 생성 - ---- - -## 🔍 근본 원인 분석 - -### 파일: `src/tools/delegate-task/constants.ts` - -#### 문제의 핵심 - -`PLAN_AGENT_SYSTEM_PREPEND` (constants.ts 234-269행)에 구조적 결함이 있었습니다: - -1. **Interactive Mode 가정** - ``` - 2. After gathering context, ALWAYS present: - - Uncertainties: List of unclear points - - Clarifying Questions: Specific questions to resolve uncertainties - - 3. ITERATE until ALL requirements are crystal clear: - - Do NOT proceed to planning until you have 100% clarity - - Ask the user to confirm your understanding - ``` - -2. **종료 조건 없음** - - "100% clarity" 요구는 객관적 측정 불가능 - - 사용자 확인 요청은 ULW mode에서 불가능 - - 무한루프로 이어짐 - -3. **ULW Mode 미감지** - - Subagent로 실행되는 경우를 구분하지 않음 - - 항상 interactive mode로 동작 시도 - -### 왜 무한루프가 발생했는가? - -``` -ULW Mode 시작 - → Sisyphus가 Plan Agent 호출 (subagent) - → Plan Agent: "100% clarity 필요" - → Clarifying questions 생성 - → 사용자 없음 (subagent) - → 다시 plan 생성 시도 - → "여전히 unclear" - → 무한루프 반복 -``` - -**핵심:** Plan Agent는 사용자와 대화하도록 설계되었지만, ULW mode에서는 사용자가 없는 subagent로 실행됨. - ---- - -## ✅ 적용된 수정 방안 - -### 수정 내용 (constants.ts) - -#### 1. SUBAGENT MODE DETECTION 섹션 추가 - -```typescript -SUBAGENT MODE DETECTION (CRITICAL): -If you received a detailed prompt with gathered context from a parent orchestrator (e.g., Sisyphus): -- You are running as a SUBAGENT -- You CANNOT directly interact with the user -- DO NOT ask clarifying questions - proceed with available information -- Make reasonable assumptions for minor ambiguities -- Generate the plan based on the provided context -``` - -#### 2. Context Gathering Protocol 수정 - -```diff -- 1. Launch background agents to gather context: -+ 1. Launch background agents to gather context (ONLY if not already provided): -``` - -**효과:** 이미 Sisyphus가 context를 수집한 경우 중복 방지 - -#### 3. Clarifying Questions → Assumptions - -```diff -- 2. After gathering context, ALWAYS present: -- - Uncertainties: List of unclear points -- - Clarifying Questions: Specific questions -+ 2. After gathering context, assess clarity: -+ - User Request Summary: Concise restatement -+ - Assumptions Made: List any assumptions for unclear points -``` - -**효과:** 질문 대신 가정 사항 문서화 - -#### 4. 무한루프 방지 - 명확한 종료 조건 - -```diff -- 3. ITERATE until ALL requirements are crystal clear: -- - Do NOT proceed to planning until you have 100% clarity -- - Ask the user to confirm your understanding -- - Resolve every ambiguity before generating the work plan -+ 3. PROCEED TO PLAN GENERATION when: -+ - Core objective is understood (even if some details are ambiguous) -+ - You have gathered context via explore/librarian (or context was provided) -+ - You can make reasonable assumptions for remaining ambiguities -+ -+ DO NOT loop indefinitely waiting for perfect clarity. -+ DOCUMENT assumptions in the plan so they can be validated during execution. -``` - -**효과:** -- "100% clarity" 요구 제거 -- 객관적인 진입 조건 제공 -- 무한루프 명시적 금지 -- Assumptions를 plan에 문서화하여 실행 중 검증 가능 - -#### 5. 철학 변경 - -```diff -- REMEMBER: Vague requirements lead to failed implementations. -+ REMEMBER: A plan with documented assumptions is better than no plan. -``` - -**효과:** Perfectionism → Pragmatism - ---- - -## 🎯 해결 메커니즘 - -### Before (무한루프) - -``` -Plan Agent 시작 - ↓ -Context gathering - ↓ -Requirements 명확한가? - ↓ NO -Clarifying questions 생성 - ↓ -사용자 응답 대기 (없음) - ↓ -다시 plan 시도 - ↓ -(무한 반복) -``` - -### After (정상 종료) - -``` -Plan Agent 시작 - ↓ -Subagent mode 감지? - ↓ YES -Context 이미 있음? → YES - ↓ -Core objective 이해? → YES - ↓ -Reasonable assumptions 가능? → YES - ↓ -Plan 생성 (assumptions 문서화) - ↓ -완료 ✓ -``` - ---- - -## 📊 영향 분석 - -### 해결되는 문제 - -1. **ULW mode 무한루프** ✓ -2. **Sisyphus에서 Plan Agent 호출 시 블로킹** ✓ -3. **작은 토큰 반복 요청** ✓ -4. **1분마다 재시도** ✓ - -### 부작용 없음 - -- Interactive mode (사용자와 직접 대화)는 여전히 작동 -- Subagent mode일 때만 다르게 동작 -- Backward compatibility 유지 - -### 추가 개선사항 - -- Assumptions를 plan에 명시적으로 문서화 -- Execution 중 validation 가능 -- 더 pragmatic한 workflow - ---- - -## 🧪 검증 방법 - -### 테스트 시나리오 - -1. **ULW mode에서 Plan Agent 호출** - ```bash - oh-my-opencode run "Complex task requiring planning. ulw" - ``` - - 예상: Plan 생성 후 정상 종료 - - 확인: 무한루프 없음 - -2. **Interactive mode (변경 없어야 함)** - ```bash - oh-my-opencode run --agent prometheus "Design X" - ``` - - 예상: Clarifying questions 여전히 가능 - - 확인: 사용자와 대화 가능 - -3. **Subagent context 제공 케이스** - - 예상: Context gathering skip - - 확인: 중복 탐색 없음 - ---- - -## 📝 수정된 파일 - -``` -src/tools/delegate-task/constants.ts -``` - -### Diff Summary - -```diff -@@ -234,22 +234,32 @@ export const PLAN_AGENT_SYSTEM_PREPEND = ` -+SUBAGENT MODE DETECTION (CRITICAL): -+[subagent 감지 및 처리 로직] -+ - MANDATORY CONTEXT GATHERING PROTOCOL: --1. Launch background agents to gather context: -+1. Launch background agents (ONLY if not already provided): - --2. After gathering context, ALWAYS present: -- - Uncertainties -- - Clarifying Questions -+2. After gathering context, assess clarity: -+ - Assumptions Made - --3. ITERATE until ALL requirements are crystal clear: -- - Do NOT proceed until 100% clarity -- - Ask user to confirm -+3. PROCEED TO PLAN GENERATION when: -+ - Core objective understood -+ - Context gathered -+ - Reasonable assumptions possible -+ -+ DO NOT loop indefinitely. -+ DOCUMENT assumptions. -``` - ---- - -## 🚀 권장 사항 - -### Immediate Actions - -1. ✅ **수정 적용 완료** - constants.ts 업데이트됨 -2. ⏳ **테스트 수행** - ULW mode에서 동작 검증 -3. ⏳ **PR 생성** - code review 요청 - -### Future Improvements - -1. **Subagent context 표준화** - - Subagent로 호출 시 명시적 플래그 전달 - - `is_subagent: true` 파라미터 추가 고려 - -2. **Assumptions validation workflow** - - Plan 실행 중 assumptions 검증 메커니즘 - - Incorrect assumptions 감지 시 재계획 - -3. **Timeout 메커니즘** - - Plan Agent가 X분 이상 걸리면 강제 종료 - - Fallback plan 생성 - -4. **Monitoring 추가** - - Plan Agent 실행 시간 측정 - - Iteration 횟수 로깅 - - 무한루프 조기 감지 - ---- - -## 📖 관련 코드 구조 - -### Call Stack - -``` -Sisyphus (ULW mode) - ↓ -task(category="deep", ...) - ↓ -executor.ts: executeBackgroundContinuation() - ↓ -prompt-builder.ts: buildSystemContent() - ↓ -constants.ts: PLAN_AGENT_SYSTEM_PREPEND (문제 위치) - ↓ -Plan Agent 실행 -``` - -### Key Functions - -1. **executor.ts:587** - `isPlanAgent()` 체크 -2. **prompt-builder.ts:11** - Plan Agent prepend 주입 -3. **constants.ts:234** - PLAN_AGENT_SYSTEM_PREPEND 정의 - ---- - -## 🎓 교훈 - -### Design Lessons - -1. **Dual Mode Support** - - Interactive vs Autonomous mode 구분 필수 - - Context 전달 방식 명확히 - -2. **Avoid Perfectionism in Agents** - - "100% clarity" 같은 주관적 조건 지양 - - 명확한 객관적 종료 조건 필요 - -3. **Document Uncertainties** - - 불확실성을 숨기지 말고 문서화 - - 실행 중 validation 가능하게 - -4. **Infinite Loop Prevention** - - 모든 반복문에 명시적 종료 조건 - - Timeout 또는 max iteration 설정 - ---- - -## 🔗 참고 자료 - -- **Issue:** #1501 - [Bug]: ULW mode will 100% cause PLAN AGENT to get stuck -- **Files Modified:** `src/tools/delegate-task/constants.ts` -- **Related Concepts:** Ultrawork mode, Plan Agent, Subagent delegation -- **Agent Architecture:** Sisyphus → Prometheus → Atlas workflow - ---- - -## ✅ Conclusion - -**Root Cause:** Plan Agent가 interactive mode를 가정했으나 ULW mode에서는 subagent로 실행되어 사용자 상호작용 불가능. "100% clarity" 요구로 무한루프 발생. - -**Solution:** Subagent mode 감지 로직 추가, clarifying questions 제거, 명확한 종료 조건 제공, assumptions 문서화 방식 도입. - -**Result:** ULW mode에서 Plan Agent가 정상적으로 plan 생성 후 종료. 무한루프 해결. - ---- - -**Status:** ✅ Fixed -**Tested:** ⏳ Pending -**Deployed:** ⏳ Pending - -**Analyst:** Sisyphus (oh-my-opencode ultrawork mode) -**Date:** 2026-02-05 -**Session:** fast-ember