trace

# TRACE — 경쟁 가설 기반 Evidence-Driven 디버깅

> "가설을 세우고, 증거로 죽여라. 살아남은 가설이 답이다."

## 사용법

```
/trace "로그인 후 간헐적으로 500 에러 발생"
/trace "특정 유저만 결제 실패"
/trace "배포 후 응답속도 3배 느려짐"
/trace "로컬에선 되는데 CI에서만 실패"
```

---

## 언제 trace를 써야 하는가

**USE WHEN:**
- 원인이 명확하지 않은 버그 (직관으로 바로 고치기 어려운 경우)
- 2회 이상 다른 곳을 수정했지만 버그가 사라지지 않는 경우
- 간헐적 / 환경 의존적 / 특정 유저에게만 발생하는 버그
- 성능 저하, 메모리 누수, 타임아웃 등 인과관계가 불명확한 경우
- "왜 이게 일어나는지" 물어봐야 하는 모든 상황

**AVOID WHEN:**
- 에러 메시지가 명확하고 수정 방향이 바로 보이는 경우 (그냥 고쳐라)
- 단순한 typo, 누락된 import, 명백한 null 체크 누락
- 이미 원인을 알고 있고 구현만 필요한 경우

---

## 핵심 계약 (The Trace Contract)

Trace 세션은 항상 아래 7개 필드를 유지한다. 이것이 작업 메모리다.

```
OBSERVATION     : [재현 가능한 증상. 구체적으로. "가끔 느림" (X) → "p99 응답 2.3s, 정상 340ms" (O)]
HYPOTHESES      : [순위화된 가설 목록. 각 가설은 반증 가능해야 함]
EVIDENCE FOR    : [각 가설을 지지하는 실제 데이터/코드 증거]
EVIDENCE AGAINST: [각 가설을 약화시키는 실제 데이터/코드 증거]
BEST EXPLANATION: [현재 가장 유력한 가설 + 신뢰도 (0-100%)]
CRITICAL UNKNOWN: [지금 당장 알 수 없어서 진단을 막는 핵심 미지수]
NEXT PROBE      : [CRITICAL UNKNOWN을 해소할 가장 효율적인 실험/탐색]
```

**규칙:**
- EVIDENCE는 반드시 실제 코드 줄, 로그, 측정값이어야 한다. "아마도", "보통은" 금지.
- 가설은 반증 가능해야 한다. "뭔가 잘못됐다"는 가설이 아니다.
- BEST EXPLANATION의 신뢰도가 85% 이상이면 진단 완료로 간주.

---

## 증거 강도 계층 (Evidence Strength Hierarchy)

증거를 수집할 때 이 순서를 따른다. 상위 증거가 하위 증거를 압도한다.

| 등급 | 유형 | 예시 |
|------|------|------|
| ⬆️ **L1** | 직접 실험 (재현 성공) | 로컬에서 버그 재현 → 코드 변경 → 해결 확인 |
| ⬆️ **L2** | 1차 소스 (코드/로그/측정) | 실제 스택트레이스, DB 쿼리 실행계획, 프로파일러 결과 |
| ⬆️ **L3** | 다중 소스 수렴 | 로그 + 메트릭 + 코드 3가지가 같은 지점을 가리킴 |
| ⬇️ **L4** | 단일 소스 추론 | 로그 하나만 보고 내린 결론 |
| ⬇️ **L5** | 정황 증거 | "이 PR 이후로 느려짐" (상관관계, 인과관계 아님) |
| ⬇️ **L6** | 직관 / 경험 | "이런 거 전에도 있었는데..." |

> **원칙**: L5/L6 증거는 가설 생성에 쓰되, 진단 확정에는 쓰지 않는다.
> L1/L2 증거 없이 "원인을 찾았다"고 선언하지 않는다.

---

## Phase 0: Observation 수집

`/trace` 시작 시 먼저 증상을 구체화한다.

### 자동 수집 (코드베이스)
```bash
# 최근 변경 이력 — 정황 증거 L5
git --no-pager log --oneline -20

# 최근 에러 패턴 탐색
grep -rn "error\|Error\|exception\|Exception" . \
  --include="*.log" -l 2>/dev/null | head -5

# 관련 설정 파일 탐색
find . \( -name "*.env*" -o -name "*.config.*" \) \
  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -10
```

### 사용자에게 필수 확인
AskUserQuestion으로 정보 수집:
1. **재현 조건**: 항상 발생? 간헐적? 특정 환경/유저에서만?
2. **최초 발생**: 언제부터? 특정 배포/변경 후?
3. **관찰 가능한 증거**: 실제 에러 메시지, 로그, 스택트레이스 있나?
4. **이미 시도한 것**: 어떤 가설로 어떤 것을 시도해봤나?

---

## Phase 1: 기본 3-레인 가설 수립

알려진 정보를 바탕으로 3개의 경쟁 가설 레인을 설정한다.

### Lane A — 코드 경로 원인
> "코드 로직 자체가 잘못됐다"

탐색 포인트:
- 최근 수정된 함수 / 모듈의 로직 오류
- Race condition, 동시성 문제
- 예외 처리 누락, 잘못된 에러 전파
- 잘못된 알고리즘 / 경계 조건 버그

```bash
# 최근 변경된 파일 탐색
git --no-pager diff HEAD~5 --name-only 2>/dev/null

# 핵심 함수 로직 확인
grep -rn "TODO\|FIXME\|HACK\|XXX" . \
  --include="*.ts" --include="*.py" --include="*.js" \
  -not -path "*/node_modules/*" | head -20
```

### Lane B — 설정·환경 원인
> "코드는 맞는데 환경/설정이 다르다"

탐색 포인트:
- 환경변수 차이 (로컬 vs 스테이징 vs 프로덕션)
- 의존성 버전 불일치 (package-lock.json drift 등)
- 인프라 설정 차이 (타임아웃, 메모리 제한, 커넥션 풀)
- 외부 서비스 상태 (DB, 캐시, 서드파티 API)

```bash
# 의존성 버전 확인
[ -f package.json ] && cat package.json | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(json.dumps(d.get('dependencies',{}), indent=2))"
[ -f requirements.txt ] && cat requirements.txt
[ -f go.mod ] && cat go.mod

# 환경 설정 파일 목록
find . -name "*.env*" -not -path "*/.git/*" 2>/dev/null
find . -name "docker-compose*" -o -name "Dockerfile*" 2>/dev/null | head -5
```

### Lane C — 측정·가정 불일치 원인
> "버그가 아니라 우리가 잘못 보고 있다"

탐색 포인트:
- 로깅/모니터링 자체의 오류 (잘못된 메트릭 집계)
- 테스트가 실제 시나리오를 커버하지 않음
- 잘못된 전제 (예: "이 함수는 항상 sorted를 받는다")
- 재현 조건을 잘못 이해하고 있는 경우

---

## Phase 2: /fleet 병렬 탐색

3개 레인을 explore 에이전트로 동시에 탐색한다.

```
# Atlas가 3개 레인을 병렬로 투입
/fleet [
  explore: "Lane A 탐색 — [증상]과 관련된 코드 로직 오류 찾기.
            최근 변경된 [관련 파일/모듈] 중심으로 탐색.
            찾은 것: 파일 경로, 코드 줄, 의심 로직 설명",

  explore: "Lane B 탐색 — [증상]과 관련된 설정/환경 차이 찾기.
            .env, config, 의존성 버전, 인프라 설정 중심 탐색.
            찾은 것: 설정 항목, 버전, 환경 간 차이점",

  explore: "Lane C 탐색 — [증상]이 실제로 문제인지 측정/가정 오류인지 확인.
            로깅 코드, 테스트 커버리지, 모니터링 설정 탐색.
            찾은 것: 측정 로직 위치, 가정이 명시된 코드, 잠재적 오해"
]
```

**Atlas의 병렬 실행 패턴:**
```bash
# background 모드로 3 레인 동시 투입
agentA=$(task explore "Lane A: [구체적 탐색 지시]" mode=background)
agentB=$(task explore "Lane B: [구체적 탐색 지시]" mode=background)
agentC=$(task explore "Lane C: [구체적 탐색 지시]" mode=background)

# 완료 후 결과 수집
read_agent $agentA
read_agent $agentB
read_agent $agentC
```

---

## Phase 3: 증거 수집 및 가설 순위화

각 레인의 결과를 Trace Contract에 채운다.

### 순위화 기준

| 기준 | 설명 |
|------|------|
| **증거 등급** | L1/L2 증거가 있는 가설 우선 |
| **설명 범위** | 더 많은 증상을 설명하는 가설 우선 |
| **단순성** | 같은 설명력이면 더 단순한 가설 우선 (Occam's Razor) |
| **반증 가능성** | 빠르게 반증 가능한 가설 우선 (실험 비용 고려) |

### 순위표 출력 형식

```
HYPOTHESIS RANKING (업데이트: [타임스탬프])
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#1 [가설 설명] — 신뢰도: [N]%
   근거: [L1/L2 증거 인용]
   약점: [반증 가능성]

#2 [가설 설명] — 신뢰도: [N]%
   근거: [증거 인용]
   약점: [반증 가능성]

#3 [가설 설명] — 신뢰도: [N]%
   근거: [증거 인용]
   약점: [반증 가능성]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRITICAL UNKNOWN: [진단을 막는 핵심 미지수]
NEXT PROBE: [다음 실험/탐색 — 구체적 명령어/방법]
```

---

## Phase 4: 반론 라운드 (Cross-Validation)

**발동 조건**: #1 가설 신뢰도가 60-85% 사이일 때. (85% 이상이면 Phase 5로 직행.)

1위 가설과 2위 가설을 oracle에게 교차 검증 요청:

```
oracle에게 위임:
"현재 #1 가설: [설명] (신뢰도 N%)
 현재 #2 가설: [설명] (신뢰도 N%)

 검토 요청:
 1. #1 가설이 틀렸다면 어떤 증거를 찾아야 하는가?
 2. #2 가설이 맞다면 #1 가설의 증거를 어떻게 설명하는가?
 3. 두 가설을 한 번에 검증할 수 있는 단일 실험이 있는가?"
```

oracle 결과를 바탕으로 Discriminating Probe를 설계:

```bash
# Discriminating Probe 예시 — 실제 코드 실행/검색
# (증상에 따라 구체적 명령어 결정)

# 로그 타임라인 분석
grep -n "ERROR\|WARN" /path/to/app.log | tail -50

# 특정 조건에서만 발생하는지 코드로 확인
grep -rn "if.*condition" src/ --include="*.ts" | grep -v test

# DB 쿼리 시간 측정 (성능 문제 시)
# EXPLAIN ANALYZE SELECT ...

# 환경변수 값 덤프 (설정 문제 시)
printenv | grep -i "DB\|API\|TOKEN\|URL" | sort
```

---

## Phase 5: 수렴 / 분기 판단

### 수렴 조건 (진단 완료)
- BEST EXPLANATION 신뢰도 ≥ 85%
- L1 또는 L2 증거가 1개 이상 존재
- 다른 가설들이 명확히 반증됨

→ **Phase 6 최종 합성**으로 이동

### 분기 조건 (추가 탐색 필요)
- BEST EXPLANATION 신뢰도 < 60%
- 여러 가설이 비슷한 신뢰도를 가짐
- CRITICAL UNKNOWN이 해소되지 않음

→ **NEXT PROBE를 실행**, Phase 2-4를 반복

### 막힌 상태 탈출 전략

| 상황 | 전략 |
|------|------|
| 재현이 안 됨 | 조건을 좁혀라. 환경변수, 데이터, 타이밍 중 무엇이 변수인가? |
| 모든 가설이 약함 | 가설을 완전히 버리고 OBSERVATION을 재검토. 다른 증상을 찾아라 |
| 증거가 상충함 | 증거의 등급을 확인. 낮은 등급 증거를 버리고 높은 등급 기준으로 판단 |
| 3 레인 모두 음성 | 4번째 가설 레인 추가: "외부 의존성 원인" (DB, API, 네트워크) |

---

## Phase 6: 최종 합성 및 진단 보고

```
═══════════════════════════════════════════════
TRACE DIAGNOSIS COMPLETE
═══════════════════════════════════════════════
증상:    [OBSERVATION 요약]
탐색:    [몇 개 레인, 몇 개 probe 실행]
결론:    ✅ 확정 | ⚠️ 유력 | ❌ 미확정

ROOT CAUSE:
  [가장 유력한 가설 — 구체적 설명]
  신뢰도: [N]% (증거 등급: L[N])

증거:
  - [L1/L2 증거 1: 파일:줄수 또는 측정값]
  - [L1/L2 증거 2: ...]

반증된 가설:
  - [가설 A]: [무엇이 이 가설을 부정했는가]
  - [가설 B]: [무엇이 이 가설을 부정했는가]

수정 방향:
  1. [구체적 첫 번째 액션 — 파일, 함수, 설정 명시]
  2. [구체적 두 번째 액션]
  3. [검증 방법: 어떻게 고쳐졌는지 확인]

미해소 미지수: (있을 경우)
  - [아직 알 수 없는 것 — 모니터링 권장]
═══════════════════════════════════════════════
```

**신뢰도 < 85%로 종료할 때:**
```
⚠️ 미확정 종료 — 신뢰도 [N]%
현재 최선 가설: [설명]
다음 단계 probe: [구체적 실험 방법]
이 정보로 /hephaestus에게 위임하거나 추가 로그 수집 후 재시작 권장.
```

---

## Atlas Heavy Mode (복잡한 버그)

3 레인으로 부족할 때 atlas heavy mode 활성화:

```
/fleet [
  explore:    "코드 경로 심층 분석 — [구체적 범위]",
  oracle:     "현재까지 수집된 증거 검토 및 반증 설계",
  hephaestus: "Discriminating Probe 코드 작성 및 실행"
]
```

**사용 시점:**
- 2회 이상 Probe를 돌렸는데 신뢰도가 오르지 않는 경우
- 버그가 여러 컴포넌트에 걸쳐 있을 가능성이 높은 경우
- 수정 비용이 높아서 진단 확실성이 필요한 경우

---

## Anti-Patterns (금지)

- ❌ 첫 번째 가설을 검증 없이 바로 수정하기 — "가장 그럴싸해 보임"은 증거가 아니다
- ❌ L5/L6 증거만으로 원인 확정 — "이 PR 이후로 느려진 것 같음"은 진단이 아니다
- ❌ 신뢰도를 명시하지 않고 "원인을 찾았다"고 선언
- ❌ CRITICAL UNKNOWN을 해소하지 않고 Phase 5 수렴 선언
- ❌ 3개 레인을 순차 탐색 — 반드시 병렬 (`/fleet`)로 실행
- ❌ Trace Contract 필드를 생략한 채 대화형으로만 진행
- ❌ 재현 조건 없이 코드 수정 시작 — 수정 후 검증 불가능해진다