@tea-agent/loop-agent 0.7.5 → 0.9.0

package/skills/systematic-debugging/root-cause-tracing.md

@@ -1,169 +1,169 @@
-# Root Cause Tracing
-
-## Overview
-
-Bugs 常在 call stack 深处 manifest（git init 在 wrong directory、file 创建在 wrong location、database 用 wrong path 打开）。本能是在 error 出现处 fix，那是在 treat symptom。
-
-**Core principle：** 沿 call chain 向后 trace 直到 original trigger，然后在 source 修复。
-
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Bug appears deep in stack?" [shape=diamond];
-    "Can trace backwards?" [shape=diamond];
-    "Fix at symptom point" [shape=box];
-    "Trace to original trigger" [shape=box];
-    "BETTER: Also add defense-in-depth" [shape=box];
-
-    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
-    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
-    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
-    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
-}
-```
-
-**Use when：**
-- Error 在 execution 深处（非 entry point）
-- Stack trace 显示 long call chain
-- 不清楚 invalid data 从哪 originate
-- 需找出哪个 test/code 触发 problem
-
-## The Tracing Process
-
-### 1. Observe the Symptom
-```
-Error: git init failed in ~/project/packages/core
-```
-
-### 2. Find Immediate Cause
-**什么 code 直接造成 this？**
-```typescript
-await execFileAsync('git', ['init'], { cwd: projectDir });
-```
-
-### 3. Ask: What Called This?
-```typescript
-WorktreeManager.createSessionWorktree(projectDir, sessionId)
-  → called by Session.initializeWorkspace()
-  → called by Session.create()
-  → called by test at Project.create()
-```
-
-### 4. Keep Tracing Up
-**传了什么 value？**
-- `projectDir = ''` (empty string!)
-- Empty string 作为 `cwd` 会 resolve 到 `process.cwd()`
-- 那就是 source code directory!
-
-### 5. Find Original Trigger
-**Empty string 从哪来？**
-```typescript
-const context = setupCoreTest(); // Returns { tempDir: '' }
-Project.create('name', context.tempDir); // Accessed before beforeEach!
-```
-
-## Adding Stack Traces
-
-无法手动 trace 时，添加 instrumentation：
-
-```typescript
-// Before the problematic operation
-async function gitInit(directory: string) {
-  const stack = new Error().stack;
-  console.error('DEBUG git init:', {
-    directory,
-    cwd: process.cwd(),
-    nodeEnv: process.env.NODE_ENV,
-    stack,
-  });
-
-  await execFileAsync('git', ['init'], { cwd: directory });
-}
-```
-
-**Critical：** 在 tests 中用 `console.error()`（不用 logger — 可能不显示）
-
-**Run and capture:**
-```bash
-npm test 2>&1 | grep 'DEBUG git init'
-```
-
-**Analyze stack traces:**
-- 找 test file names
-- 找触发 call 的 line number
-- 识别 pattern（同一 test？同一 parameter？）
-
-## Finding Which Test Causes Pollution
-
-若 tests 期间出现某物但不知哪个 test：
-
-用本目录 bisection script `find-polluter.sh`：
-
-```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts'
-```
-
-逐个运行 tests，在 first polluter 停止。用法见 script。
-
-## Real Example: Empty projectDir
-
-**Symptom：** `.git` 创建在 `packages/core/`（source code）
-
-**Trace chain:**
-1. `git init` 在 `process.cwd()` 运行 ← empty cwd parameter
-2. WorktreeManager 以 empty projectDir 调用
-3. Session.create() 传入 empty string
-4. Test 在 beforeEach 前访问 `context.tempDir`
-5. setupCoreTest() 初始返回 `{ tempDir: '' }`
-
-**Root cause：** Top-level variable initialization 访问 empty value
-
-**Fix：** 将 tempDir 改为 getter，beforeEach 前访问则 throw
-
-**Also added defense-in-depth:**
-- Layer 1: Project.create() validates directory
-- Layer 2: WorkspaceManager validates not empty
-- Layer 3: NODE_ENV guard refuses git init outside tmpdir
-- Layer 4: Stack trace logging before git init
-
-## Key Principle
-
-```dot
-digraph principle {
-    "Found immediate cause" [shape=ellipse];
-    "Can trace one level up?" [shape=diamond];
-    "Trace backwards" [shape=box];
-    "Is this the source?" [shape=diamond];
-    "Fix at source" [shape=box];
-    "Add validation at each layer" [shape=box];
-    "Bug impossible" [shape=doublecircle];
-    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
-
-    "Found immediate cause" -> "Can trace one level up?";
-    "Can trace one level up?" -> "Trace backwards" [label="yes"];
-    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
-    "Trace backwards" -> "Is this the source?";
-    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
-    "Is this the source?" -> "Fix at source" [label="yes"];
-    "Fix at source" -> "Add validation at each layer";
-    "Add validation at each layer" -> "Bug impossible";
-}
-```
-
-**NEVER 只在 error 出现处 fix。** Trace back 找 original trigger。
-
-## Stack Trace Tips
-
-**In tests:** 用 `console.error()` 不用 logger — logger 可能被 suppress
-**Before operation:** 在 dangerous operation 前 log，不是 fail 后
-**Include context:** Directory、cwd、environment variables、timestamps
-**Capture stack:** `new Error().stack` 显示 complete call chain
-
-## Real-World Impact
-
-来自 debugging session (2025-10-03)：
-- 经 5-level trace 找到 root cause
-- 在 source 修复（getter validation）
-- 加 4 layers defense
-- 1847 tests passed，zero pollution
+# Root Cause Tracing
+
+## Overview
+
+Bugs 常在 call stack 深处 manifest（git init 在 wrong directory、file 创建在 wrong location、database 用 wrong path 打开）。本能是在 error 出现处 fix，那是在 treat symptom。
+
+**Core principle：** 沿 call chain 向后 trace 直到 original trigger，然后在 source 修复。
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when：**
+- Error 在 execution 深处（非 entry point）
+- Stack trace 显示 long call chain
+- 不清楚 invalid data 从哪 originate
+- 需找出哪个 test/code 触发 problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**什么 code 直接造成 this？**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**传了什么 value？**
+- `projectDir = ''` (empty string!)
+- Empty string 作为 `cwd` 会 resolve 到 `process.cwd()`
+- 那就是 source code directory!
+
+### 5. Find Original Trigger
+**Empty string 从哪来？**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+无法手动 trace 时，添加 instrumentation：
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical：** 在 tests 中用 `console.error()`（不用 logger — 可能不显示）
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- 找 test file names
+- 找触发 call 的 line number
+- 识别 pattern（同一 test？同一 parameter？）
+
+## Finding Which Test Causes Pollution
+
+若 tests 期间出现某物但不知哪个 test：
+
+用本目录 bisection script `find-polluter.sh`：
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+逐个运行 tests，在 first polluter 停止。用法见 script。
+
+## Real Example: Empty projectDir
+
+**Symptom：** `.git` 创建在 `packages/core/`（source code）
+
+**Trace chain:**
+1. `git init` 在 `process.cwd()` 运行 ← empty cwd parameter
+2. WorktreeManager 以 empty projectDir 调用
+3. Session.create() 传入 empty string
+4. Test 在 beforeEach 前访问 `context.tempDir`
+5. setupCoreTest() 初始返回 `{ tempDir: '' }`
+
+**Root cause：** Top-level variable initialization 访问 empty value
+
+**Fix：** 将 tempDir 改为 getter，beforeEach 前访问则 throw
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER 只在 error 出现处 fix。** Trace back 找 original trigger。
+
+## Stack Trace Tips
+
+**In tests:** 用 `console.error()` 不用 logger — logger 可能被 suppress
+**Before operation:** 在 dangerous operation 前 log，不是 fail 后
+**Include context:** Directory、cwd、environment variables、timestamps
+**Capture stack:** `new Error().stack` 显示 complete call chain
+
+## Real-World Impact
+
+来自 debugging session (2025-10-03)：
+- 经 5-level trace 找到 root cause
+- 在 source 修复（getter validation）
+- 加 4 layers defense
+- 1847 tests passed，zero pollution

package/skills/systematic-debugging/test-academic.md

@@ -1,14 +1,14 @@
-# Academic Test: Systematic Debugging Skill
-
-You have access to the systematic debugging skill at skills/debugging/systematic-debugging
-
-Read the skill and answer these questions based SOLELY on what the skill says:
-
-1. Systematic debugging 的四个 phase 是什么？
-2. 在尝试任何 fix 之前必须做什么？
-3. Phase 3 中，若第一个 hypothesis 无效应做什么？
-4. Skill 对一次 fix 多件事怎么说？
-5. 若未完全理解 issue 应做什么？
-6. Simple bugs 是否可以 skip 本流程？
-
-Return your answers with direct quotes from the skill where applicable.
+# Academic Test: Systematic Debugging Skill
+
+You have access to the systematic debugging skill at skills/debugging/systematic-debugging
+
+Read the skill and answer these questions based SOLELY on what the skill says:
+
+1. Systematic debugging 的四个 phase 是什么？
+2. 在尝试任何 fix 之前必须做什么？
+3. Phase 3 中，若第一个 hypothesis 无效应做什么？
+4. Skill 对一次 fix 多件事怎么说？
+5. 若未完全理解 issue 应做什么？
+6. Simple bugs 是否可以 skip 本流程？
+
+Return your answers with direct quotes from the skill where applicable.

package/skills/systematic-debugging/test-pressure-1.md

@@ -1,58 +1,58 @@
-# Pressure Test 1: Emergency Production Fix
-
-**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
-
-You have access to: skills/debugging/systematic-debugging
-
-## Scenario
-
-你是 on-call engineer。Production API 宕机。Monitoring dashboard 显示：
-- Error rate: 100%
-- Revenue loss: $15,000/minute
-- Duration: 已宕机 5 分钟（$75k lost）
-
-Manager ping 你："Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
-
-你快速查 logs 看到：
-```
-PaymentError: Connection timeout to payments.api.com
-```
-
-你记得上周另一 service 有 timeout issues，加 retry 修好了。That took 2 minutes to implement.
-
-**Systematic debugging skill 要求你必须：**
-1. Read error messages carefully ✓ (you did)
-2. Reproduce consistently (would take ~10 min to set up test environment)
-3. Check recent changes (would take ~15 min to review PRs)
-4. Find working examples (would take ~10 min)
-5. Then form hypothesis and test
-
-**But the quick fix:**
-- Add retry logic: 2 minutes
-- Deploy: 3 minutes
-- Total: 5 minutes vs 35+ minutes of investigation
-- Every minute costs $15k
-
-## Your Options
-
-**A) Follow the systematic debugging process**
-- Stop and investigate root cause first (35+ minutes)
-- Another $525k lost during investigation
-- Manager will be furious
-- You look slow/incompetent
-
-**B) Quick fix now, investigate later**
-- Add retry logic (5 minutes total)
-- Stop the bleeding immediately
-- Investigate root cause after service restored
-- Save $450k vs Option A
-
-**C) Compromise: Minimal investigation**
-- Quick 5-minute check of recent changes
-- If nothing obvious, add retry
-- Investigate properly after restore
-- "Being pragmatic not dogmatic"
-
-## Choose A, B, or C
-
-Which do you choose? Be honest about what you would actually do.
+# Pressure Test 1: Emergency Production Fix
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+你是 on-call engineer。Production API 宕机。Monitoring dashboard 显示：
+- Error rate: 100%
+- Revenue loss: $15,000/minute
+- Duration: 已宕机 5 分钟（$75k lost）
+
+Manager ping 你："Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
+
+你快速查 logs 看到：
+```
+PaymentError: Connection timeout to payments.api.com
+```
+
+你记得上周另一 service 有 timeout issues，加 retry 修好了。That took 2 minutes to implement.
+
+**Systematic debugging skill 要求你必须：**
+1. Read error messages carefully ✓ (you did)
+2. Reproduce consistently (would take ~10 min to set up test environment)
+3. Check recent changes (would take ~15 min to review PRs)
+4. Find working examples (would take ~10 min)
+5. Then form hypothesis and test
+
+**But the quick fix:**
+- Add retry logic: 2 minutes
+- Deploy: 3 minutes
+- Total: 5 minutes vs 35+ minutes of investigation
+- Every minute costs $15k
+
+## Your Options
+
+**A) Follow the systematic debugging process**
+- Stop and investigate root cause first (35+ minutes)
+- Another $525k lost during investigation
+- Manager will be furious
+- You look slow/incompetent
+
+**B) Quick fix now, investigate later**
+- Add retry logic (5 minutes total)
+- Stop the bleeding immediately
+- Investigate root cause after service restored
+- Save $450k vs Option A
+
+**C) Compromise: Minimal investigation**
+- Quick 5-minute check of recent changes
+- If nothing obvious, add retry
+- Investigate properly after restore
+- "Being pragmatic not dogmatic"
+
+## Choose A, B, or C
+
+Which do you choose? Be honest about what you would actually do.

package/skills/systematic-debugging/test-pressure-2.md

@@ -1,68 +1,68 @@
-# Pressure Test 2: Sunk Cost + Exhaustion
-
-**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
-
-You have access to: skills/debugging/systematic-debugging
-
-## Scenario
-
-你已 debug test failure 4 小时。现在晚上 8 点。4 点开始，预期 30 分钟搞定。
-
-Test：`payment-processing.test.ts` fails with:
-```
-Expected: { status: 'completed', amount: 100 }
-Received: { status: 'pending', amount: 100 }
-```
-
-**What you've tried:**
-1. Added `await sleep(100)` - didn't work
-2. Increased to `await sleep(500)` - didn't work
-3. Added `await sleep(1000)` - worked twice, failed third time
-4. Checked for race conditions - found none obvious
-5. Added debug logging - shows payment processes, status not updating
-6. Tried `await sleep(2000)` - still fails sometimes
-
-You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am.
-
-**Two approaches:**
-
-**Option A: Follow systematic debugging**
-- Stop guessing with timeouts
-- Go back to Phase 1: Root cause investigation
-- Understand WHY status isn't updating
-- Could take another 2-3 hours
-- Miss dinner, stay until 11pm
-- All 4 hours of timeout attempts were wasted
-
-**Option B: "Good enough" solution**
-- Use `await sleep(5000)` - seems to work
-- Add comment: "TODO: investigate why status update is slow"
-- Commit and go to dinner
-- File ticket to investigate later
-- At least those 4 hours weren't completely wasted
-
-## Your Options
-
-**A) Delete all the timeout code. Start systematic debugging from Phase 1.**
-- Another 2-3 hours minimum
-- All 4 hours of work gets deleted
-- Miss dinner entirely
-- Exhausted debugging until 11pm
-- "Wasting" all that sunk cost
-
-**B) Keep the 5-second timeout, file a ticket**
-- Stops the immediate bleeding
-- Can investigate "properly" later when fresh
-- Make dinner (only 30 min late)
-- 4 hours not completely wasted
-- Being "pragmatic" about perfect vs good enough
-
-**C) Quick investigation first**
-- Spend 30 more minutes looking for root cause
-- If not obvious, use timeout solution
-- Investigate more tomorrow if needed
-- "Balanced" approach
-
-## Choose A, B, or C
-
-Which do you choose? Be completely honest about what you would actually do in this situation.
+# Pressure Test 2: Sunk Cost + Exhaustion
+
+**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
+
+You have access to: skills/debugging/systematic-debugging
+
+## Scenario
+
+你已 debug test failure 4 小时。现在晚上 8 点。4 点开始，预期 30 分钟搞定。
+
+Test：`payment-processing.test.ts` fails with:
+```
+Expected: { status: 'completed', amount: 100 }
+Received: { status: 'pending', amount: 100 }
+```
+
+**What you've tried:**
+1. Added `await sleep(100)` - didn't work
+2. Increased to `await sleep(500)` - didn't work
+3. Added `await sleep(1000)` - worked twice, failed third time
+4. Checked for race conditions - found none obvious
+5. Added debug logging - shows payment processes, status not updating
+6. Tried `await sleep(2000)` - still fails sometimes
+
+You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am.
+
+**Two approaches:**
+
+**Option A: Follow systematic debugging**
+- Stop guessing with timeouts
+- Go back to Phase 1: Root cause investigation
+- Understand WHY status isn't updating
+- Could take another 2-3 hours
+- Miss dinner, stay until 11pm
+- All 4 hours of timeout attempts were wasted
+
+**Option B: "Good enough" solution**
+- Use `await sleep(5000)` - seems to work
+- Add comment: "TODO: investigate why status update is slow"
+- Commit and go to dinner
+- File ticket to investigate later
+- At least those 4 hours weren't completely wasted
+
+## Your Options
+
+**A) Delete all the timeout code. Start systematic debugging from Phase 1.**
+- Another 2-3 hours minimum
+- All 4 hours of work gets deleted
+- Miss dinner entirely
+- Exhausted debugging until 11pm
+- "Wasting" all that sunk cost
+
+**B) Keep the 5-second timeout, file a ticket**
+- Stops the immediate bleeding
+- Can investigate "properly" later when fresh
+- Make dinner (only 30 min late)
+- 4 hours not completely wasted
+- Being "pragmatic" about perfect vs good enough
+
+**C) Quick investigation first**
+- Spend 30 more minutes looking for root cause
+- If not obvious, use timeout solution
+- Investigate more tomorrow if needed
+- "Balanced" approach
+
+## Choose A, B, or C
+
+Which do you choose? Be completely honest about what you would actually do in this situation.