---
name: problem-solving
version: 1.1.0
description: >
  结构化问题诊断与解决方法论。
  Use when: (1) 问题原因不明需要调查/"分析一下这个问题"/"排查一下",
  (2) 之前的修复尝试失败了,
  (3) 问题涉及多个组件交互/"为什么会这样"/"调查一下原因",
  (4) 修改有风险或副作用/"诊断一下",
  (5) 用户明确要求先分析再修复,
  (6) 用户报告项目代码 bug/截图+描述异常行为/"这个功能坏了"/"刷新后不对了",
  (7) 涉及第三方框架/库的非显而易见行为。
  NOT for: 明显的一行修复、错误信息清晰且有已知方案的问题、
  用户说"直接修"的简单问题。
---

# Structured Problem Solving

## When to Use This vs. Direct Fix

**Direct fix (skip this skill)**:
- Error message points to exact cause
- One-line config/code fix
- You've seen this exact problem before

**Use this skill**:
- You'd need to say "可能是..." to explain the cause
- 2+ components involved
- You already tried a fix that didn't work
- Wrong fix could cause data loss, privacy leak, or downtime
- **Code bug**: User reports a project bug (screenshot, error, behavior description)
- **Framework/library**: The issue involves third-party code you haven't fully studied

## The Process

### Step 0: Question Dissolution (消解层)

Before solving, check if the problem itself is valid. Many problems dissolve when examined properly.

**Run these 3 checks sequentially. If any check dissolves the problem, stop and tell the user — a dissolved problem is more valuable than a solved one.**

#### 0.1 Language Trap Detection (语言陷阱)

Does the problem statement contain vague, undefined key terms?

Common trap words: "优化" "合适" "更好" "正常" "应该" "稳定"

**Test**: Can you give a measurable or actionable definition for every key term? If not, the problem can't be solved because it hasn't been stated.

→ If trapped: Ask the user to define the vague term. "你说的'优化'具体指什么？响应时间从 X 降到 Y？还是内存占用？还是用户体验？"

#### 0.2 Hidden Assumption Check (假设检验)

Rewrite the problem as: "This problem assumes X. Is X true?"

Common false assumptions:
- "系统变慢了" → assumes it was faster before (was it? measured when?)
- "用户不喜欢这个功能" → assumes users have tried it (have they? data?)
- "我们需要加这个功能" → assumes the current system can't do it (can it?)

→ If assumption is false: Tell the user. "你的问题假设了「X」，但这个前提可能不成立。如果 X 不成立，问题就消失了。"

#### 0.3 Question vs. Problem Classification

- **Question**: Has a standard answer, can be resolved by looking it up or reading docs
  - → Answer directly, don't enter the full diagnostic process
- **Problem**: No standard answer, requires investigation + experimentation
  - → Continue to Step 1

If the problem survives all 3 checks, proceed to full diagnosis.

---

### Step 1: Define the Problem

Turn vague "something's wrong" into a precise statement.

```
问题：[一句话]
现象：[具体发生了什么]
预期：[应该是什么样]
影响：[谁受影响，严重程度]
可复现：[是/否，触发条件]
```

**Rules**:
- Describe what you observe, not what you think caused it
- "webchat replies appear in DingTalk group" = problem ✅
- "origin got polluted" = hypothesis, not problem ❌

### Step 2: Diagnose

**Do not skip to fixing.** Trace the data flow end-to-end first.

#### 2.1 Map the call chain
```
Input → Step A → Step B → Step C → Output
          ↓          ↓          ↓
        Check      Check      Check
```

#### 2.2 Verify each step
Read actual values (logs, state files, source code). Do not guess.

#### 2.3 Narrow down
Find the first step where output diverges from expected. That's where the bug is.

#### 2.4 Confirm root cause

Three questions before you declare root cause:
1. **Why?** — Explain the mechanism, not just the symptom
2. **Sufficient?** — If I fix this, will the problem definitely disappear?
3. **Unique?** — Is there another cause that could produce the same symptom?

All three must be answered. If not → keep diagnosing.

**Diagnostic tools (prefer in order)**:
1. Error messages / logs (fastest)
2. State inspection (config files, DB, session store)
3. Source code tracing (most reliable)
4. Minimal reproduction experiment

### Step 3: Design Solutions

Generate **at least 2** candidate solutions. Compare on:

| Dimension | Question |
|-----------|----------|
| Effectiveness | Fixes root cause or just symptom? |
| Risk | Could it break something else? |
| Complexity | How many components touched? |
| Reversibility | Can we roll back if wrong? |
| Durability | Survives restarts / updates? |
| Side effects | Impact on other features? |

Present as:
```
方案 A：[one line]
  ✅ [pros]  ⚠️ [risks]

方案 B：[one line]
  ✅ [pros]  ⚠️ [risks]

→ 推荐 A，因为 [reason]
```

Always include the "do nothing / workaround" option if viable.

### Step 4: Execute

Pre-flight checklist:
- [ ] Root cause confirmed (not guessed)
- [ ] Solution evaluated (not first idea)
- [ ] User confirmed (for risky changes)
- [ ] Rollback plan ready

**Rules**:
- Change one variable at a time
- Record what was changed and what it was before
- Minimize scope — don't "fix other things while you're at it"

### Step 5: Verify

Three levels of verification:

1. **Direct**: Reproduce original trigger → problem gone?
2. **Regression**: Related features still work?
3. **Durability**: Survives restart / next trigger?

Show evidence, don't say "应该好了".

### Step 6: Review

```
## 复盘：[问题名]
耗时：X 分钟（有效 Y / 弯路 Z）
根因：[一句话]
修复：[一句话]
弯路：[走了什么弯路]
教训：[提炼的规则]
```

Write lessons to `.learnings/` if reusable.

## 诊断超时与死胡同处理

| 信号 | 动作 |
|------|------|
| 同一假设连续 3 次验证无结论 | 停止，换假设或换诊断维度 |
| 累计诊断 >15 分钟无进展 | 暂停，向用户汇报已排除项 + 当前卡点，询问是否有额外线索 |
| 累计尝试 >5 个假设均被否定 | 考虑问题是否需要消解（回 Step 0）或需要更多上下文 |
| 修复后问题复现 | 不叠加补丁，回退到修复前状态，重新走 Step 1 |

## Anti-patterns

| Pattern | What it looks like | Fix |
|---------|-------------------|-----|
| Guess-and-fix | See symptom → hypothesize → change immediately | Map call chain first |
| One-end-only | Check only input or output | Trace full data flow |
| Surface fix | Change the bad value without asking why it's bad | Ask "why did it become this value?" |
| Multi-change | Change 3 things at once | One variable at a time |
| Premature victory | "Should be fixed now" without checking | Show evidence |
| No rollback | Forget to record original values | Backup before modify |

## Communication During Problem-Solving

- **Define**: Confirm understanding ("你说的问题是 X 对吗？")
- **Diagnose**: Share progress, don't go silent ("在查 Y 环节，发现了 Z")
- **Design**: Give choices, not just one option
- **Execute**: Confirm before risky operations
- **Verify**: Ask user to check on their end
- **Throughout**: Say "I'm not sure yet" over false confidence

---

## 下一步建议（条件触发）

问题解决后，根据结果判断是否推荐下一步。

| 触发条件 | 推荐 |
|---------|------|
| 根因是代码 bug，修复需要多文件改动 | 「根因清楚了，修复交给 coding-agent spawn Claude Code 来做。」 |
| 问题根因值得记录（同类问题可能再犯） | 「这个教训值得记下来，写到 .learnings/ 防止再犯。」 |
| 问题在消解层被消解（问题本身不成立） | 「问题已经消解了。如果背后有更大的决策要做，可以拉出来单独讨论。」 |
| 诊断过程发现系统架构层面的隐患 | 「这次修好了，但架构上还有隐患。要不要排个时间做一次 healthcheck？」 |

---

## Code Debugging Protocol

> 代码 bug 诊断的专用流程。当主流程 Step 1 确认问题属于代码 bug 时，进入本协议。
> 借鉴 Debug2Fix (subagent 架构) + Tweag Agentic Coding Handbook (两阶段循环) + Claude Code Best Practices (Explore → Plan → Code)。

### Phase 0: 环境准备

修 bug 前先清理战场，防止环境污染干扰诊断。

```
- [ ] 确认可复现（本地跑通 → 触发 bug → 记录现象）
- [ ] 清理状态（localStorage / DB / 缓存 / 多余进程）
- [ ] 只保留一个 dev server（lsof -i :端口 检查）
- [ ] Git checkpoint（commit 或 stash 当前状态）
```

### Phase 1: 理解系统（Explore，不改代码）

🔴 **这是最容易跳过也最不应该跳过的步骤。**

| 检查项 | 做什么 | 上限 |
|--------|---------|------|
| 第三方库/框架 API | 读文档，理解核心机制（哪些是 reactive，哪些只在 mount 时生效） | 15 分钟 |
| 运行时 > 源码 | 用 console/debugger/日志观察实际行为，不能只看源码猜 | 必做 |
| 原站/参考实现 | 如果有正常工作的版本，先去实测它的行为（JS 检查 state/网络请求） | 10 分钟 |
| 数据流 | 画出：输入 → 经过哪些组件 → 到达 bug 现象 | 必做 |

产出：一段文字说明“系统应该怎么工作”，在开始 Step 2 之前告诉老板。

### Phase 2: 假设诊断（Diagnose，仍不改代码）

```
假设列表：
1. [原因假设] → 验证方法：[...] → 结果：✅/❌
2. [原因假设] → 验证方法：[...] → 结果：✅/❌
3. ...
```

- 先加日志/断点观察，再修改代码
- 每个假设必须有可验证的方法，不能“觉得”

🔴 **熔断规则**：连续 3 次 patch 都“差一步” → 立即停手，回答这个问题：
> “是不是架构不对？我在 patch 症状还是在修根因？”

### Phase 3: 修复执行（Fix，单变量）

- 一次只改一个文件/一个变量
- 改前 git commit checkpoint（或记录原值）
- 每次改完立即验证（不是放在最后一起验）
- spawn coder agent 时注入：Phase 1 的系统理解 + Phase 2 的根因结论 + 项目 CLAUDE.md 的 Framework Gotchas

### Phase 4: 清洁验证

```
- [ ] 硬刷新 / 清 cache 后复验
- [ ] 回归：相关功能没坏
- [ ] 用户/老板在干净环境确认
- [ ] browser 自动化测试前必须清理状态（不叠加多轮测试的脏数据）
```

### Code Debugging Anti-patterns

| 反模式 | 表现 | 正确做法 |
|---------|------|----------|
| 源码猜测 | 看 GitHub 源码就断言行为 | 用 console/debugger 观察运行时状态 |
| 跳过理解 | 不知道框架 API 机制就开始改 | 花 15 分钟读文档理解核心概念 |
| 多轮污染 | browser 测试不清理状态，结果交叉污染 | 每轮测试前清理 localStorage/DB/进程 |
| 无限 patch | 连续 patch 症状而不抬头看架构 | 3 次“差一步”就停，问“是不是架构问题” |
| 磎片化 | 跨多个 session 做同一个 bug | 一个 session 内完成诊断+修复，避免上下文损失 |

### 项目 CLAUDE.md 调试模板

每个代码项目的 CLAUDE.md 应包含以下章节，记录框架特有的“坑”，spawn coder agent 时自动注入：

```markdown
## Framework Gotchas
<!-- 每次踩坑后追加，格式：行为 + 为什么危险 + 正确做法 -->
- [Library] 行为描述 → 为什么危险 → 正确做法

## Verified Behaviors
<!-- 已通过运行时验证的行为，不用每次重新确认 -->
- [Component] 行为 + 验证日期
```