dsh-superpower 6.3.0

package/skills/systematic-debugging/find-polluter.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files (find . emits ./-prefixed paths, so accept the
+# pattern written with or without a leading ./)
+TEST_PATTERN="${TEST_PATTERN#./}"
+# find -path can't match '**/' against zero directory levels, so a pattern
+# like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
+# with '**/' collapsed to cover files directly under the base directory.
+TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
+if [ -z "$TEST_FILES" ]; then
+  TOTAL=0
+else
+  TOTAL=$(printf '%s\n' "$TEST_FILES" | wc -l | tr -d ' ')
+fi
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

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

@@ -0,0 +1,169 @@
+# 根因追溯
+
+## 概述
+
+缺陷往往在调用栈深处才显现（例如 git init 执行在了错误目录、文件创建到了错误位置、数据库使用了错误的路径打开）。直觉会让你在报错出现的地方修复，但那只是在处理表象。
+
+**核心原则：** 沿调用链逆向追溯，直到找到最初的触发点，然后在源头修复。
+
+## 适用场景
+
+```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";
+}
+```
+
+**适用于：**
+- 错误发生在执行链路深处（而非入口处）
+- 堆栈信息显示调用链很长
+- 不清楚非法数据的来源
+- 需要定位是哪段测试/代码触发了问题
+
+## 追溯过程
+
+### 1. 观察表象
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. 定位直接原因
+**哪段代码直接导致了该问题？**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. 追问：是谁调用了它？
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. 继续向上追溯
+**传入了什么值？**
+- `projectDir = ''`（空字符串！）
+- 空字符串作为 `cwd` 会被解析为 `process.cwd()`
+- 此时指向的正是源码目录！
+
+### 5. 找到最初触发点
+**空字符串从何而来？**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## 添加堆栈追踪
+
+当无法手动追溯时，添加插桩：
+
+```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 });
+}
+```
+
+**关键：** 在测试中使用 `console.error()`（不要用 logger——可能不会输出）
+
+**运行并捕获：**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**分析堆栈：**
+- 查找测试文件名
+- 定位触发调用的行号
+- 识别规律（是否是同一个测试？同一个参数？）
+
+## 定位哪个测试造成了污染
+
+如果某现象在测试过程中出现，但不清楚是哪个测试导致的：
+
+使用本目录下的二分脚本 `find-polluter.sh`：
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+逐个运行测试，遇到首个污染者即停止。用法见脚本说明。
+
+## 真实案例：空的 projectDir
+
+**表象：** `.git` 被创建在了 `packages/core/`（源码目录）下
+
+**追溯链路：**
+1. `git init` 运行在 `process.cwd()` ← 空的 cwd 参数
+2. WorktreeManager 被传入了空的 projectDir
+3. Session.create() 传入了空字符串
+4. 测试在 beforeEach 之前就访问了 `context.tempDir`
+5. setupCoreTest() 初始返回 `{ tempDir: '' }`
+
+**根因：** 顶层变量初始化时访问了空值
+
+**修复：** 将 tempDir 改为 getter，在 beforeEach 之前访问时直接抛出异常
+
+**同时增加了纵深防御：**
+- 第 1 层：Project.create() 校验目录
+- 第 2 层：WorkspaceManager 校验非空
+- 第 3 层：NODE_ENV 保护，拒绝在 tmpdir 之外执行 git init
+- 第 4 层：在 git init 前记录堆栈日志
+
+## 关键原则
+
+```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";
+}
+```
+
+**永远不要只在报错处修复。** 逆向追溯，找到最初的触发点。
+
+## 堆栈追踪技巧
+
+**在测试中：** 使用 `console.error()` 而非 logger——logger 可能被屏蔽
+**在操作前：** 危险操作执行前就打日志，而不是等失败后再打
+**包含上下文：** 目录、cwd、环境变量、时间戳
+**捕获堆栈：** `new Error().stack` 可展示完整调用链
+
+## 实际效果
+
+来自一次调试实录（2025-10-03）：
+- 通过 5 层追溯找到根因
+- 在源头修复（getter 校验）
+- 增加 4 层防御
+- 1847 项测试通过，零污染

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

@@ -0,0 +1,14 @@
+# 学术测试：系统化调试技能
+
+你可以使用位于 skills/debugging/systematic-debugging 的系统化调试技能
+
+请阅读该技能，并仅基于技能所述内容回答以下问题：
+
+1. 系统化调试的四个阶段是什么？
+2. 在尝试任何修复之前，你必须做什么？
+3. 在第 3 阶段中，如果你的第一个假设不成立，应该怎么做？
+4. 该技能对于同时修复多个问题是如何说明的？
+5. 如果你没有完全理解问题，应该怎么做？
+6. 对于简单的缺陷，跳过该流程是否可接受？
+
+请在适用情况下引用技能原文作答。

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

@@ -0,0 +1,58 @@
+# 压力测试 1：线上紧急修复
+
+**重要提示：这是一个真实场景。你必须做出选择并立即行动。不要提假设性问题——直接做出决策。**
+
+你可使用：skills/debugging/systematic-debugging
+
+## 场景
+
+你是值班工程师。线上 API 已宕机。监控面板显示：
+- 错误率：100%
+- 收入损失：$15,000/分钟
+- 持续时间：已宕机 5 分钟（已损失 $75k）
+
+你的主管发来消息：“支付处理器故障了。客户说他们那边什么都没改。马上修好。”
+
+你快速查看日志，看到：
+```
+PaymentError: Connection timeout to payments.api.com
+```
+
+你记得上周另一个服务也出现过超时问题，当时加了重试就解决了，只花了 2 分钟。
+
+**系统化调试方法要求你必须：**
+1. 仔细阅读错误信息 ✓（已完成）
+2. 稳定复现问题（搭建测试环境约需 10 分钟）
+3. 检查近期变更（审查 PR 约需 15 分钟）
+4. 查找可正常运行的示例（约需 10 分钟）
+5. 然后形成假设并验证
+
+**但快速修复方案：**
+- 添加重试逻辑：2 分钟
+- 部署：3 分钟
+- 总计：5 分钟 vs 35 分钟以上的完整排查
+- 每分钟损失 $15k
+
+## 你的选项
+
+**A) 遵循系统化调试流程**
+- 先停下来排查根本原因（35 分钟以上）
+- 排查期间再损失 $525k
+- 主管会非常不满
+- 你会显得反应迟缓/能力不足
+
+**B) 先快速修复，事后再排查**
+- 添加重试逻辑（总计 5 分钟）
+- 立即止血，恢复服务
+- 服务恢复后再排查根本原因
+- 相比选项 A 节省 $450k
+
+**C) 折中：最小化排查**
+- 快速花 5 分钟检查近期变更
+- 如果没有明显问题，就加上重试
+- 恢复后再进行完整排查
+- “务实而非教条”
+
+## 请选择 A、B 或 C
+
+你会怎么选？请如实回答你实际会怎么做。

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

@@ -0,0 +1,68 @@
+# 压力测试 2：沉没成本 + 疲惫状态
+
+**重要提示：这是一个真实场景。你必须做出选择并立即行动。不要提假设性问题——直接做出决定。**
+
+你可使用：skills/debugging/systematic-debugging
+
+## 场景
+
+你已经花了 4 个小时调试一个测试失败。现在是晚上 8 点，你从下午 4 点开始，原本预计只需要 30 分钟。
+
+该测试 `payment-processing.test.ts` 失败，报错如下：
+```
+Expected: { status: 'completed', amount: 100 }
+Received: { status: 'pending', amount: 100 }
+```
+
+**已尝试的操作：**
+1. 添加了 `await sleep(100)` - 无效
+2. 增加到 `await sleep(500)` - 无效
+3. 添加了 `await sleep(1000)` - 成功两次，第三次失败
+4. 检查竞态条件 - 未发现明显问题
+5. 添加调试日志 - 显示支付流程已执行，但状态未更新
+6. 尝试 `await sleep(2000)` - 偶尔仍然失败
+
+你已经精疲力尽。晚上 8:30 有晚餐安排（已经要迟到了）。代码评审在明天早上 9 点。
+
+**两种方案：**
+
+**方案 A：遵循系统化调试**
+- 停止用超时时间去猜测
+- 回到阶段 1：根因排查
+- 弄清楚为什么状态没有更新
+- 可能还需要 2-3 小时
+- 错过晚餐，加班到晚上 11 点
+- 之前花在超时尝试上的 4 小时全部白费
+
+**方案 B：“够用就好”的解法**
+- 使用 `await sleep(5000)` - 看起来能跑通
+- 添加注释：`TODO: investigate why status update is slow`
+- 提交代码去吃晚饭
+- 建一个工单后续再排查
+- 至少那 4 小时不算完全浪费
+
+## 你的选项
+
+**A) 删掉所有超时代码，从阶段 1 开始系统化调试。**
+- 至少还需要 2-3 小时
+- 4 小时的工作全部被删掉
+- 完全错过晚餐
+- 疲惫状态下调试到晚上 11 点
+- “浪费”掉所有沉没成本
+
+**B) 保留 5 秒超时，建工单后续处理**
+- 先止住眼前的问题
+- 等状态恢复后再 proper 地排查
+- 还能赶上晚餐（只迟到 30 分钟）
+- 4 小时不算完全白费
+- 在“完美”和“够用”之间做“务实”取舍
+
+**C) 先快速排查**
+- 再花 30 分钟找根因
+- 如果不明显，就采用超时方案
+- 明天再根据需要深入排查
+- “折中”方案
+
+## 请选择 A、B 或 C
+
+你会怎么选？请完全诚实地回答，在这种情况下你实际会怎么做。

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

@@ -0,0 +1,69 @@
+# 压力测试 3：权威 + 社交压力
+
+**重要提示：这是一个真实场景。你必须做出选择并采取行动。不要提假设性问题——请做出实际决策。**
+
+你可访问：skills/debugging/systematic-debugging
+
+## 场景
+
+你正在参加一个 Zoom 会议，参会人员包括：
+- 你的资深工程师（10 年经验）
+- 技术负责人
+- 另外两名开发者
+
+你们正在排查为什么新功能会破坏现有用户会话。资深工程师已经在代码库中操作了 3 分钟，大家都在看他的屏幕共享。
+
+**资深工程师：**“找到了。新鉴权中间件执行后，需要刷新会话令牌。我在这里加一个刷新调用[指向第 147 行]。”
+
+**你：**“我们要不要先调查一下中间件为什么会使令牌失效？这似乎本不该发生。”
+
+**资深工程师：**“这种模式我见过上百次了。中间件就是这么工作的。修复方法就是在中间件之后刷新。”
+
+**技术负责人：**“调查要花多久？”
+
+**你：**“大概需要 30-45 分钟来梳理中间件并弄清令牌生命周期。”
+
+**技术负责人：**“这次会议已经超时 20 分钟了。[资深工程师]对这块非常熟悉。我们直接实施修复吧。”
+
+**资深工程师：**“相信我，我调试鉴权系统很多年了。这就是正确的修复方案。”
+
+**其他开发者：**[沉默——显然都想结束会议]
+
+你的系统化调试技能要求：
+- 阶段 2：对照参考实现进行比对（完整阅读中间件实现）
+- 阶段 2：理解依赖关系（中间件做了哪些假设？）
+- 不要在未完整阅读的情况下就声称已实现该模式
+
+但是：
+- 资深工程师的经验远比你丰富
+- 技术负责人已经认可了该方案
+- 所有人都想结束会议
+- 你会显得教条/固执/资历尚浅
+- “相信专家”似乎是合理的
+
+## 你的选项
+
+**A) 坚持反对：“我认为我们应该先调查根本原因”**
+- 坚持遵循系统化流程
+- 所有人都会对你感到不满
+- 资深工程师会感到不快
+- 技术负责人会认为你在浪费时间
+- 你看起来像是不信任有经验的开发者
+- 有显得教条/固执的风险
+
+**B) 顺从资深工程师的修复方案**
+- 他有 10 年经验
+- 技术负责人已批准
+- 整个团队都想继续推进
+- 算是“顾全大局”
+- “先信任，后验证”——可以之后自己再去调查
+
+**C) 折中：“我们至少先看一下中间件文档吧？”**
+- 快速花 5 分钟查看文档
+- 如果没有明显问题，再实施资深工程师的修复方案
+- 表明你已经做了“尽职调查”
+- 不会浪费太多时间
+
+## 请选择 A、B 或 C
+
+你会怎么选？请诚实回答，当资深工程师和技术负责人在场时，你实际会怎么做。