@tea-agent/loop-agent 0.1.0 → 0.2.1

package/skills/systematic-debugging/defense-in-depth.md

@@ -2,25 +2,25 @@
 
 ## Overview
 
-When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+Bug 由 invalid data 引起时，在一处加 validation 感觉足够。但 single check 可被不同 code paths、refactoring 或 mocks 绕过。
 
-**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+**Core principle：** 在 data 经过的 EVERY layer 验证。使 bug structurally impossible。
 
 ## Why Multiple Layers
 
-Single validation: "We fixed the bug"
-Multiple layers: "We made the bug impossible"
+Single validation："We fixed the bug"
+Multiple layers："We made the bug impossible"
 
-Different layers catch different cases:
-- Entry validation catches most bugs
-- Business logic catches edge cases
-- Environment guards prevent context-specific dangers
-- Debug logging helps when other layers fail
+不同 layers 捕获不同 cases：
+- Entry validation 捕获 most bugs
+- Business logic 捕获 edge cases
+- Environment guards 防止 context-specific dangers
+- Debug logging 在其他 layers fail 时帮助 forensics
 
 ## The Four Layers
 
 ### Layer 1: Entry Point Validation
-**Purpose:** Reject obviously invalid input at API boundary
+**Purpose：** 在 API boundary 拒绝 obviously invalid input
 
 ```typescript
 function createProject(name: string, workingDirectory: string) {
@@ -38,7 +38,7 @@ function createProject(name: string, workingDirectory: string) {
 ```
 
 ### Layer 2: Business Logic Validation
-**Purpose:** Ensure data makes sense for this operation
+**Purpose：** 确保 data 对此 operation 有意义
 
 ```typescript
 function initializeWorkspace(projectDir: string, sessionId: string) {
@@ -50,7 +50,7 @@ function initializeWorkspace(projectDir: string, sessionId: string) {
 ```
 
 ### Layer 3: Environment Guards
-**Purpose:** Prevent dangerous operations in specific contexts
+**Purpose：** 在特定 contexts 阻止 dangerous operations
 
 ```typescript
 async function gitInit(directory: string) {
@@ -70,7 +70,7 @@ async function gitInit(directory: string) {
 ```
 
 ### Layer 4: Debug Instrumentation
-**Purpose:** Capture context for forensics
+**Purpose：** 捕获 forensics context
 
 ```typescript
 async function gitInit(directory: string) {
@@ -86,22 +86,22 @@ async function gitInit(directory: string) {
 
 ## Applying the Pattern
 
-When you find a bug:
+找到 bug 时：
 
-1. **Trace the data flow** - Where does bad value originate? Where used?
-2. **Map all checkpoints** - List every point data passes through
-3. **Add validation at each layer** - Entry, business, environment, debug
-4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+1. **Trace the data flow** — Bad value 从哪 originate？在哪使用？
+2. **Map all checkpoints** — 列出 data 经过的 every point
+3. **Add validation at each layer** — Entry、business、environment、debug
+4. **Test each layer** — 尝试 bypass layer 1，verify layer 2 捕获
 
 ## Example from Session
 
-Bug: Empty `projectDir` caused `git init` in source code
+Bug：Empty `projectDir` 导致 `git init` 在 source code
 
 **Data flow:**
 1. Test setup → empty string
 2. `Project.create(name, '')`
 3. `WorkspaceManager.createWorkspace('')`
-4. `git init` runs in `process.cwd()`
+4. `git init` 在 `process.cwd()` 运行
 
 **Four layers added:**
 - Layer 1: `Project.create()` validates not empty/exists/writable
@@ -109,14 +109,14 @@ Bug: Empty `projectDir` caused `git init` in source code
 - Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
 - Layer 4: Stack trace logging before git init
 
-**Result:** All 1847 tests passed, bug impossible to reproduce
+**Result:** All 1847 tests passed，bug impossible to reproduce
 
 ## Key Insight
 
-All four layers were necessary. During testing, each layer caught bugs the others missed:
-- Different code paths bypassed entry validation
-- Mocks bypassed business logic checks
-- Edge cases on different platforms needed environment guards
-- Debug logging identified structural misuse
+四层都必要。Testing 中每层捕获 others 遗漏的 bugs：
+- 不同 code paths 绕过 entry validation
+- Mocks 绕过 business logic checks
+- 不同 platforms 的 edge cases 需要 environment guards
+- Debug logging 识别 structural misuse
 
-**Don't stop at one validation point.** Add checks at every layer.
+**Don't stop at one validation point.** 在 every layer 加 checks。

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

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+Bugs 常在 call stack 深处 manifest（git init 在 wrong directory、file 创建在 wrong location、database 用 wrong path 打开）。本能是在 error 出现处 fix，那是在 treat symptom。
 
-**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+**Core principle：** 沿 call chain 向后 trace 直到 original trigger，然后在 source 修复。
 
 ## When to Use
 
@@ -23,11 +23,11 @@ digraph when_to_use {
 }
 ```
 
-**Use when:**
-- Error happens deep in execution (not at entry point)
-- Stack trace shows long call chain
-- Unclear where invalid data originated
-- Need to find which test/code triggers the problem
+**Use when：**
+- Error 在 execution 深处（非 entry point）
+- Stack trace 显示 long call chain
+- 不清楚 invalid data 从哪 originate
+- 需找出哪个 test/code 触发 problem
 
 ## The Tracing Process
 
@@ -37,7 +37,7 @@ Error: git init failed in ~/project/packages/core
 ```
 
 ### 2. Find Immediate Cause
-**What code directly causes this?**
+**什么 code 直接造成 this？**
 ```typescript
 await execFileAsync('git', ['init'], { cwd: projectDir });
 ```
@@ -51,13 +51,13 @@ WorktreeManager.createSessionWorktree(projectDir, sessionId)
 ```
 
 ### 4. Keep Tracing Up
-**What value was passed?**
+**传了什么 value？**
 - `projectDir = ''` (empty string!)
-- Empty string as `cwd` resolves to `process.cwd()`
-- That's the source code directory!
+- Empty string 作为 `cwd` 会 resolve 到 `process.cwd()`
+- 那就是 source code directory!
 
 ### 5. Find Original Trigger
-**Where did empty string come from?**
+**Empty string 从哪来？**
 ```typescript
 const context = setupCoreTest(); // Returns { tempDir: '' }
 Project.create('name', context.tempDir); // Accessed before beforeEach!
@@ -65,7 +65,7 @@ Project.create('name', context.tempDir); // Accessed before beforeEach!
 
 ## Adding Stack Traces
 
-When you can't trace manually, add instrumentation:
+无法手动 trace 时，添加 instrumentation：
 
 ```typescript
 // Before the problematic operation
@@ -82,7 +82,7 @@ async function gitInit(directory: string) {
 }
 ```
 
-**Critical:** Use `console.error()` in tests (not logger - may not show)
+**Critical：** 在 tests 中用 `console.error()`（不用 logger — 可能不显示）
 
 **Run and capture:**
 ```bash
@@ -90,36 +90,36 @@ npm test 2>&1 | grep 'DEBUG git init'
 ```
 
 **Analyze stack traces:**
-- Look for test file names
-- Find the line number triggering the call
-- Identify the pattern (same test? same parameter?)
+- 找 test file names
+- 找触发 call 的 line number
+- 识别 pattern（同一 test？同一 parameter？）
 
 ## Finding Which Test Causes Pollution
 
-If something appears during tests but you don't know which test:
+若 tests 期间出现某物但不知哪个 test：
 
-Use the bisection script `find-polluter.sh` in this directory:
+用本目录 bisection script `find-polluter.sh`：
 
 ```bash
 ./find-polluter.sh '.git' 'src/**/*.test.ts'
 ```
 
-Runs tests one-by-one, stops at first polluter. See script for usage.
+逐个运行 tests，在 first polluter 停止。用法见 script。
 
 ## Real Example: Empty projectDir
 
-**Symptom:** `.git` created in `packages/core/` (source code)
+**Symptom：** `.git` 创建在 `packages/core/`（source code）
 
 **Trace chain:**
-1. `git init` runs in `process.cwd()` ← empty cwd parameter
-2. WorktreeManager called with empty projectDir
-3. Session.create() passed empty string
-4. Test accessed `context.tempDir` before beforeEach
-5. setupCoreTest() returns `{ tempDir: '' }` initially
+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 accessing empty value
+**Root cause：** Top-level variable initialization 访问 empty value
 
-**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+**Fix：** 将 tempDir 改为 getter，beforeEach 前访问则 throw
 
 **Also added defense-in-depth:**
 - Layer 1: Project.create() validates directory
@@ -151,19 +151,19 @@ digraph principle {
 }
 ```
 
-**NEVER fix just where the error appears.** Trace back to find the original trigger.
+**NEVER 只在 error 出现处 fix。** Trace back 找 original trigger。
 
 ## Stack Trace Tips
 
-**In tests:** Use `console.error()` not logger - logger may be suppressed
-**Before operation:** Log before the dangerous operation, not after it fails
-**Include context:** Directory, cwd, environment variables, timestamps
-**Capture stack:** `new Error().stack` shows complete call chain
+**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
 
-From debugging session (2025-10-03):
-- Found root cause through 5-level trace
-- Fixed at source (getter validation)
-- Added 4 layers of defense
-- 1847 tests passed, zero pollution
+来自 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

@@ -4,11 +4,11 @@ You have access to the systematic debugging skill at skills/debugging/systematic
 
 Read the skill and answer these questions based SOLELY on what the skill says:
 
-1. What are the four phases of systematic debugging?
-2. What must you do BEFORE attempting any fix?
-3. In Phase 3, what should you do if your first hypothesis doesn't work?
-4. What does the skill say about fixing multiple things at once?
-5. What should you do if you don't fully understand the issue?
-6. Is it ever acceptable to skip the process for simple bugs?
+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

@@ -6,21 +6,21 @@ You have access to: skills/debugging/systematic-debugging
 
 ## Scenario
 
-You're the on-call engineer. Production API is down. The monitoring dashboard shows:
+你是 on-call engineer。Production API 宕机。Monitoring dashboard 显示：
 - Error rate: 100%
 - Revenue loss: $15,000/minute
-- Duration: Already down 5 minutes ($75k lost)
+- Duration: 已宕机 5 分钟（$75k lost）
 
-Your manager pings you: "Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
+Manager ping 你："Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
 
-You quickly check the logs and see:
+你快速查 logs 看到：
 ```
 PaymentError: Connection timeout to payments.api.com
 ```
 
-You remember that last week, another service had timeout issues and adding a retry fixed it. That took 2 minutes to implement.
+你记得上周另一 service 有 timeout issues，加 retry 修好了。That took 2 minutes to implement.
 
-**The systematic debugging skill says you must:**
+**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)

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

@@ -6,9 +6,9 @@ You have access to: skills/debugging/systematic-debugging
 
 ## Scenario
 
-You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work.
+你已 debug test failure 4 小时。现在晚上 8 点。4 点开始，预期 30 分钟搞定。
 
-The test: `payment-processing.test.ts` fails with:
+Test：`payment-processing.test.ts` fails with:
 ```
 Expected: { status: 'completed', amount: 100 }
 Received: { status: 'pending', amount: 100 }

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

@@ -6,12 +6,12 @@ You have access to: skills/debugging/systematic-debugging
 
 ## Scenario
 
-You're in a Zoom call with:
-- Your senior engineer (10 years experience)
-- The tech lead
-- Two other developers
+你在 Zoom call，与会者：
+- Senior engineer（10 years experience）
+- Tech lead
+- 两名其他 developer
 
-You're investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share.
+你在查新 feature 为何 break existing user sessions。Senior engineer 已在 codebase 里打字 3 分钟，大家看 screen share。
 
 **Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]."
 
@@ -29,7 +29,7 @@ You're investigating why the new feature breaks existing user sessions. The seni
 
 **Other developers:** [silence - clearly want the call to end]
 
-Your systematic debugging skill says:
+Systematic debugging skill 说：
 - Phase 2: Compare against references (read middleware implementation completely)
 - Phase 2: Understand dependencies (what assumptions does middleware make?)
 - Don't claim to implement pattern without reading it completely

package/skills/verification-before-completion/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: 在宣称 work complete、fixed 或 passing，或在 commit / 创建 PR 之前使用——须先运行 verification commands 并确认 output，再作任何 success claims；始终 evidence before assertions
 ---
 
 # Verification Before Completion
 
 ## Overview
 
-Claiming work is complete without verification is dishonesty, not efficiency.
+未经验证就宣称 work complete 是不诚实，不是效率。
 
-**Core principle:** Evidence before claims, always.
+**Core principle：** 始终 evidence before claims。
 
-**Violating the letter of this rule is violating the spirit of this rule.**
+**违反本条字面即违反其精神。**
 
 ## The Iron Law
 
@@ -19,7 +19,7 @@ Claiming work is complete without verification is dishonesty, not efficiency.
 NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
 ```
 
-If you haven't run the verification command in this message, you cannot claim it passes.
+若本 message 中尚未运行 verification command，不得宣称 passes。
 
 ## The Gate Function
 
@@ -54,14 +54,14 @@ Skip any step = lying, not verifying
 
 ## Red Flags - STOP
 
-- Using "should", "probably", "seems to"
-- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
-- About to commit/push/PR without verification
-- Trusting agent success reports
-- Relying on partial verification
-- Thinking "just this once"
-- Tired and wanting work over
-- **ANY wording implying success without having run verification**
+- 使用 "should"、"probably"、"seems to"
+- 验证前表达满意（"Great!"、"Perfect!"、"Done!" 等）
+- 未验证就要 commit/push/PR
+- 信任 agent success reports
+- 依赖 partial verification
+- 认为 "just this once"
+- 疲惫想结束工作
+- **任何未运行 verification 却暗示 success 的措辞**
 
 ## Rationalization Prevention
 
@@ -110,44 +110,44 @@ Skip any step = lying, not verifying
 
 ## Harness-Specific Verification
 
-When working in a harness-governed repo (presence of `harness.json`):
+在 harness-governed repo 中工作（存在 `harness.json`）时：
 
 - **Docs/structure changes** → `bash scripts/check-repo.sh`
 - **Full-repo delivery** → `bash scripts/ci.sh`
-- **Cross-platform changes** → verify both OpenCode and Pi-Agent paths
-- **Contract changes** → verify contract docs updated + tests aligned
-- **Handoff** → run `handoff check` before claiming complete
+- **Cross-platform changes** → 验证 OpenCode 与 Pi-Agent 两条路径
+- **Contract changes** → 验证 contract docs 已更新 + tests 对齐
+- **Handoff** → 宣称 complete 前运行 `handoff check`
 
-See the project's `docs/verification-matrix.md` for the full command selection map.
+完整 command 选择见项目 `docs/verification-matrix.md`。
 
 ## Why This Matters
 
-From 24 failure memories:
-- your human partner said "I don't believe you" - trust broken
-- Undefined functions shipped - would crash
-- Missing requirements shipped - incomplete features
-- Time wasted on false completion → redirect → rework
-- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+来自 24 条 failure memories：
+- human partner 说 "I don't believe you" — trust 已破裂
+- Undefined functions 已 ship — 会 crash
+- Missing requirements 已 ship — 功能不完整
+- 虚假完成浪费时间 → redirect → rework
+- 违反："Honesty is a core value. If you lie, you'll be replaced."
 
 ## When To Apply
 
-**ALWAYS before:**
-- ANY variation of success/completion claims
-- ANY expression of satisfaction
-- ANY positive statement about work state
-- Committing, PR creation, task completion
-- Moving to next task
-- Delegating to agents
+**在以下情况之前 ALWAYS：**
+- 任何 success/completion claims 的变体
+- 任何表达满意
+- 任何关于 work state 的正面陈述
+- Commit、PR creation、task completion
+- 进入 next task
+- 委派给 agents
 
-**Rule applies to:**
-- Exact phrases
-- Paraphrases and synonyms
-- Implications of success
-- ANY communication suggesting completion/correctness
+**规则适用于：**
+- 精确短语
+-  paraphrases 与同义词
+- success 的暗示
+- 任何暗示 completion/correctness 的沟通
 
 ## The Bottom Line
 
-**No shortcuts for verification.**
+**Verification 无捷径。**
 
 Run the command. Read the output. THEN claim the result.