@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/skills/distilled/distilled-systematic-debugging.md

@@ -1,306 +1,154 @@
 ---
 name: distilled-systematic-debugging
-version: 0.1.0-distilled
-description: 'Distilled IT-universal skill: systematic-debugging (score 5/5)'
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: systematic-debugging (score 4.5/5)'
 spawn_agent: harness-debug-full
 keywords:
   - systematic
   - debugging
-  - debug
-  - 调试
-  - bug
-  - 修复
-  - fix
-  - hotfix
-  - 报错
-  - 异常
-  - error
-  - 不工作
-  - 失败
-  - failed
-  - crash
-  - 问题
 rubric_version: 2
 distilled_from:
-  - upstream: https://github.com/winspan/claude-forge.git
+  - upstream: https://github.com/obra/superpowers.git
     license: MIT
-    commit: 7d96b86c
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
     paths:
-      - official/official-debug.md
-distilled_at: '2026-05-27T01:53:11.488Z'
-distilled_by: claude-sonnet-4-6
-it_universal_score: 5
+      - systematic-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+  - upstream: https://github.com/affaan-m/ECC.git
+    license: MIT
+    commit: 928076cc08cbb31e8549cea2883b4f51811de1c8
+    paths:
+      - agent-introspection-debugging/SKILL.md
+distilled_at: '2026-06-15T00:55:01.895Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 4.5
 it_universal_dims:
   d1: 1
-  d2: 1
+  d2: 0.5
   d3: 1
   d4: 1
   d5: 1
-it_universal_rationale: Lang-agnostic systematic debug methodology; D1-D5 all high.
----
-
-## 触发条件
-
-- 某个行为无法稳定复现，或复现路径不明确，导致无法有效定位根因
-- 日志、监控或测试输出显示异常，但根因不清晰（如事件丢失、统计不一致、接口报错）
-- 近期变更引入了回归，需要系统性地缩小问题范围
-- 修复方案已实施，但缺乏验证手段确认根因已消除且无副作用
-- 多个组件协作时出现边界问题（如队列堆积、认证失效、缓存失效），难以单点定位
-
----
-
-## 核心原则
-
-1. **先复现，再分析** — 未能稳定复现的 bug 无法被可靠修复；复现步骤本身就是对问题的精确描述。
-2. **一次只验证一个假设** — 同时改多处会使因果关系模糊，导致"修好了但不知道为什么"。
-3. **最小化修复，直指根因** — 绕过症状的补丁会积累技术债；修复应消除根本原因，而非掩盖表现。
-4. **修复前先写能复现 bug 的测试** — 测试锁定预期行为，防止同一问题在未来悄然回归。
-5. **日志优于猜测** — 在关键路径加可观测性（日志、指标、断言），让系统状态可见，而非依赖直觉推断。
-
----
-
-## 工作流
-
-1. **复现**
-   记录完整上下文：运行环境、输入数据、期望行为、实际行为。确认 bug 可在受控条件下稳定触发，再进入下一步。
-
-2. **收集信息**
-   查阅日志（服务日志、错误日志、审计日志）、检查监控指标、确认当前系统状态（进程是否运行、连接是否建立、队列是否堆积）。
-
-3. **缩小范围**
-   使用二分法排查代码路径或配置项。借助版本控制工具（如 `git bisect`）定位引入问题的变更。逐层排除：网络层 → 服务层 → 业务逻辑层 → 持久层。
-
-4. **建立假设**
-   基于已有证据，清晰陈述一个可证伪的假设，例如："问题出在 X 组件的 Y 行为上，因为观察到 Z 现象。"
-
-5. **验证假设**
-   通过最小化实验（添加日志、临时断言、单元测试、隔离调用）验证或推翻假设。若推翻，返回步骤 4 建立新假设。
-
-6. **实施修复**
-   先写一个能复现 bug 的测试，再实施最小化修复。修复应针对根因，而非症状。避免在同一 PR 中混入无关重构。
-
-7. **验证修复**
-   确认：① 原始 bug 不再复现；② 新增测试通过；③ 现有测试套件无回归；④ 边界场景（空输入、并发、超时）行为符合预期。
-
-8. **记录与沉淀**
-   将根因分析、修复思路、关键决策记录到项目知识库或 PR 描述中，供团队后续参考。
-
----
-
-## 反模式
-
-- **靠猜测修复**：跳过复现和假设验证，直接"试一试"改代码。表面上节省时间，实际上引入更多不确定性，且无法确认问题是否真正解决。
-
-- **同时修改多处**：一次性改动多个可疑点，导致无法判断哪个改动起了作用，也无法安全回滚单一变更。
-
-- **修复症状而非根因**：例如用重试掩盖超时、用默认值掩盖空指针，问题会在不同场景下以新面目重现。
-
-- **跳过回归验证**：修复后只确认原始场景通过，未运行完整测试套件，导致隐性回归流入主干。
-
-- **不记录调试过程**：团队成员在未来遇到相同问题时重复投入相同的排查成本，知识无法复用。
-
+it_universal_rationale: >-
+  Four-phase root-cause methodology (investigate → pattern → hypothesis → implement) with a
+  3+-failures-means-architectural-problem heuristic; language- and toolchain-neutral; directly
+  portable to any debugging session in any codebase.
 ---
 
-## 验证标准
+# Systematic Debugging
 
-- [ ] bug 有明确的、可稳定复现的步骤
-- [ ] 根因已被识别，而非仅症状被消除
-- [ ] 修复前存在能复现 bug 的测试用例
-- [ ] 修复后该测试用例通过
-- [ ] 现有测试套件全部通过，无新增失败
-- [ ] 关键边界场景（并发、超时、空输入、服务不可达）已验证
-- [ ] 修复内容最小化，未混入无关变更
-- [ ] 根因分析和修复决策已记录（PR 描述、知识库条目或注释）
+## When to use
+- Any test failure, bug report, or unexpected behaviour — before proposing fixes
+- Performance problems, build failures, integration breakage
+- **Especially** when under time pressure, when an "obvious" fix hasn't worked, or when you've already tried multiple fixes
+- **Do not skip** for "simple" bugs — simple bugs have root causes too; the process is fast for them
 
----
-
-## 适用范围
-
-本技能适用于以下通用层次，与具体技术栈无关：
-
-- **后端服务**：接口报错、事件处理异常、队列堆积、认证失效、重试逻辑错误
-- **持久层**：Schema 迁移失败、数据不一致、索引冲突、聚合统计偏差
-- **前端 / 客户端**：状态同步异常、渲染错误、网络请求失败
-- **CLI 工具**：命令行参数解析错误、配置读取失败、进程通信异常
-- **调度器 / 后台任务**：任务重复执行、任务丢失、TTL 超期处理异常
-- **知识库 / 构建流水线**：增量构建缓存失效、降级占位未自愈、依赖缺失导致的静默失败
-
-> // 项目特定，复用时跳过
->
-> 对于使用本地 Unix socket 通信的守护进程架构，常见的额外排查点包括：socket 文件是否存在（`lsof -U`）、认证 token 是否在进程重启后同步、事件队列文件是否因守护进程不可达而堆积。这些属于该架构模式的特定表现，通用调试流程同样适用。
-
----
-
-## 上游对照
-
-本技能综合自以下上游来源：
+## Core idea
 
-- **上游 systematic-debugging（见 frontmatter）**：提供了通用五步调试框架（复现→隔离→假设→修复→验证）以及针对特定项目架构的高频踩坑模式。
+Random fixes waste time and create new bugs; symptom-level patches mask underlying issues.
+The core principle is: always find the root cause before attempting any fix.
+The methodology gates progress through four sequential phases — Root Cause → Pattern Analysis → Hypothesis Testing → Implementation — so each phase must be complete before the next begins.
+The payoff is measurable: systematic debugging takes 15–30 minutes versus 2–3 hours of guess-and-check thrashing, with a first-time fix rate near 95 % versus ≈ 40 %.
+The single most important escalation heuristic: **if three or more distinct fixes have failed, stop fixing symptoms and question the architecture.**
 
-通用部分（§工作流、§核心原则、§反模式）直接源自上游的通用步骤，已去除所有项目特定符号、路径引用和内部模块名称。项目特定调试模式中可泛化的经验（如"聚合表与事件表短暂不一致是预期行为"、"SDK 重试与业务层重试叠加会导致双层退避"）已抽象为通用原则融入正文；不可泛化的部分（具体文件路径、内部类名、特定端口）已在 §适用范围 的附录中隔离标注。
-
----
-
-## 示例（伪代码）
-
-以下以"后端服务事件处理后持久层未更新"为场景，演示完整调试流程。
-
-### 场景描述
-
-用户触发某操作后，查询接口返回的数据未反映该操作，但操作本身没有报错。
-
-### 步骤 1：复现
+## The Iron Law
 
 ```
-环境：本地开发环境，服务版本 v1.2.3
-输入：POST /events  { type: "user_action", payload: {...} }
-期望：GET /events 返回列表中包含新事件
-实际：GET /events 返回列表中不包含新事件
-可稳定复现：是
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 ```
 
-### 步骤 2：收集信息
+If Phase 1 is incomplete, no fix may be proposed.
 
-```pseudocode
-// 检查服务是否正在运行
-check_process_running("backend-service")
+## Steps
 
-// 检查服务日志
-tail_logs("backend-service", level="warn|error", lines=100)
+### Phase 1 — Root Cause Investigation
 
-// 检查持久层连接
-check_connection("persistence-layer")
+1. **Read error messages completely.** Do not skim warnings; read stack traces to the bottom; note exact line numbers, file paths, and error codes. They often contain the solution.
 
-// 检查队列状态（如有）
-count_pending_items("event-queue")
-```
+2. **Reproduce consistently.** Establish exact reproduction steps. If the issue is not reliably reproducible, gather more data — do not guess.
 
-### 步骤 3：缩小范围
+3. **Check recent changes.** Review git diff, recent commits, new dependencies, config changes, and environment differences. Something changed; find it.
 
-```pseudocode
-// 分层排查
-layer_1: 请求是否到达服务？
-  → 检查访问日志，确认 POST 请求有 200 响应
+4. **Instrument boundaries in multi-component systems.**  
+   For any system with multiple layers (e.g., API → service → database; build → sign → deploy):
+   - At each component boundary, log what data *enters* and what *exits*
+   - Verify config/environment propagation at every layer
+   - **Run once to collect evidence** showing *where* it breaks
+   - Analyse that evidence to identify the failing component
+   - Only then investigate that specific component in depth
 
-layer_2: 服务是否处理了事件？
-  → 在事件处理入口加日志，确认 handler 被调用
+5. **Trace data flow for deep call-stack errors.**  
+   Start at the failing point and trace backwards: what called this with the bad value? Keep tracing up the call chain until you find the origination point. Fix at the source, not at the symptom.
 
-layer_3: 持久化是否被调用？
-  → 在写入操作前后加日志，确认 insert/upsert 被执行
+### Phase 2 — Pattern Analysis
 
-layer_4: 写入是否成功？
-  → 检查是否有异常被静默捕获（catch 块只打 warn 不重新抛出）
-```
-
-发现：`layer_4` 的日志显示 `warn: insert failed - unique constraint`，异常被静默忽略，函数返回了成功状态。
-
-### 步骤 4：建立假设
-
-```
-假设：事件处理器在写入失败时静默忽略了唯一约束冲突，
-     导致调用方误认为写入成功，实际数据未持久化。
-```
-
-### 步骤 5：验证假设
-
-```pseudocode
-// 构造触发唯一约束冲突的测试用例
-test_case = {
-  description: "重复事件 ID 应返回错误或幂等成功",
-  input: duplicate_event_id,
-  expected: either ERROR or idempotent_success_with_existing_data
-}
+1. Find working examples of similar behaviour in the same codebase.
+2. Read the reference implementation **completely** — never skim.
+3. List every difference between working and broken, no matter how small.
+4. Understand all dependencies: required config, environment assumptions, shared state.
 
-run_test(test_case)
-// 结果：确认 handler 返回 success 但数据库无新行 → 假设成立
-```
+### Phase 3 — Hypothesis and Testing
 
-### 步骤 6：实施修复
+1. **Form one specific hypothesis:** *"I think X is the root cause because Y."* Write it down.
+2. Make the **smallest possible change** to test it — one variable at a time.
+3. Did it work? → proceed to Phase 4. Did not work? → form a **new** hypothesis; do **not** stack additional fixes on top.
+4. When you don't know, say so. Research or ask; do not pretend.
 
-```pseudocode
-// 修复前：异常被静默
-function handle_event(event):
-  try:
-    db.insert(event)
-  catch UniqueConstraintError as e:
-    log.warn("insert failed", e)   // ← 静默，调用方不知道失败了
-    return { success: true }       // ← 错误：返回了假成功
+### Phase 4 — Implementation
 
-// 修复后：明确区分幂等成功与真实错误
-function handle_event(event):
-  try:
-    db.insert(event)
-    return { success: true }
-  catch UniqueConstraintError:
-    existing = db.find_by_id(event.id)
-    return { success: true, idempotent: true, data: existing }
-  catch DatabaseError as e:
-    log.error("insert failed", e)
-    raise e                        // ← 向上传播，让调用方感知失败
-```
+1. **Create a failing test case first** — the simplest possible automated reproduction. The test must fail before the fix.
+2. **Implement exactly one fix** that addresses the confirmed root cause. No "while I'm here" changes; no bundled refactoring.
+3. **Verify:** test now passes, no regressions introduced, issue is actually resolved.
+4. **If the fix doesn't work:** stop, return to Phase 1 with the new information gathered. Never attempt a fourth fix without re-investigating from scratch.
+5. **If 3 or more fixes have failed — question the architecture.**  
+   Signals of an architectural problem (not a symptom problem):
+   - Each fix reveals a new failure in a different place
+   - Fixes require "massive refactoring" to implement cleanly
+   - Fixing one symptom creates new symptoms elsewhere  
+   
+   At this point: stop, document the pattern, and discuss whether the underlying design needs to change before any more fixes are attempted.
 
-**多语言对照（同一逻辑）：**
+## Anti-patterns
 
-```typescript
-// TypeScript
-async function handleEvent(event: Event): Promise<Result> {
-  try {
-    await db.insert(event);
-    return { success: true };
-  } catch (err) {
-    if (isUniqueConstraintError(err)) {
-      const existing = await db.findById(event.id);
-      return { success: true, idempotent: true, data: existing };
-    }
-    logger.error("insert failed", err);
-    throw err;
-  }
-}
-```
+Stop and return to Phase 1 whenever you catch yourself thinking:
 
-```python
-# Python
-def handle_event(event: Event) -> Result:
-    try:
-        db.insert(event)
-        return Result(success=True)
-    except UniqueConstraintError:
-        existing = db.find_by_id(event.id)
-        return Result(success=True, idempotent=True, data=existing)
-    except DatabaseError as e:
-        logger.error("insert failed: %s", e)
-        raise
-```
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "I'll add multiple changes at once and run tests"
+- "It's probably X, let me fix that" — assumption without evidence
+- "I don't fully understand, but this might work"
+- "Pattern says X but I'll adapt it differently" — without reading it completely
+- Proposing a solution before tracing the data flow
+- "One more fix attempt" when two have already failed
 
-```go
-// Go
-func handleEvent(event Event) (Result, error) {
-    err := db.Insert(event)
-    if err == nil {
-        return Result{Success: true}, nil
-    }
-    if isUniqueConstraint(err) {
-        existing, _ := db.FindByID(event.ID)
-        return Result{Success: true, Idempotent: true, Data: existing}, nil
-    }
-    logger.Error("insert failed", "err", err)
-    return Result{}, err
-}
-```
+### Common rationalisations
 
-### 步骤 7：验证修复
+| Excuse | Reality |
+|---|---|
+| "Issue is simple, don't need process" | Simple issues have root causes. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is faster than thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write the test after the fix works" | Untested fixes don't stick. A failing test first proves the fix. |
+| "Multiple fixes at once saves time" | Can't isolate what worked; introduces new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question the design. |
 
-```pseudocode
-run_test("重复事件 ID 返回幂等成功")          // ✓ 通过
-run_test("新事件正常写入并可查询")             // ✓ 通过
-run_test("数据库连接失败时错误向上传播")        // ✓ 通过
-run_full_test_suite()                        // ✓ 无回归
-```
+## Quick reference
 
-### 步骤 8：记录
+| Phase | Key activities | Gate to move forward |
+|---|---|---|
+| 1 — Root Cause | Read errors; reproduce; check changes; instrument boundaries | Understand WHAT failed and WHY |
+| 2 — Pattern | Find working examples; read reference completely; list differences | Root difference identified |
+| 3 — Hypothesis | State single specific theory; test minimally | Confirmed or replaced with new hypothesis |
+| 4 — Implementation | Failing test first; one fix; verify; escalate at 3 failures | Bug resolved, tests pass, no regressions |
 
-```
-根因：事件处理器将唯一约束冲突静默为成功，导致调用方无法感知写入失败。
-修复：区分幂等冲突（返回已有数据）与真实错误（向上传播），消除假成功状态。
-影响范围：所有依赖该 handler 返回值判断写入结果的调用方需确认行为符合预期。
-```
+## References
+- Upstream: https://github.com/obra/superpowers.git