# problem-solving

Adopt this skill: https://proskills.md/skills/other/lovensky1992-wk-problem-solving

Page: https://proskills.md/skills/other/lovensky1992-wk-problem-solving
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 11709
sha: c0ce4d8f9b9d1ea3c525c6669658646fb5622e26
upstream: https://github.com/lovensky1992-wk/problem-solving/blob/HEAD/SKILL.md

````text
---
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] 行为 + 验证日期
```
````

## File: README.md
size: 2018
sha: 313b2946e1f238188824c254e0c9a157d6dcde21
upstream: https://github.com/lovensky1992-wk/problem-solving/blob/HEAD/README.md

````text
# Problem Solving

Structured problem diagnosis and resolution methodology for OpenClaw.

## Features

- 🔍 **Systematic Diagnosis**: Map call chains and trace data flow end-to-end
- 🎯 **Root Cause Analysis**: Three-question framework to confirm true causes
- 🛠️ **Solution Design**: Compare multiple approaches on effectiveness, risk, and reversibility
- ✅ **Rigorous Verification**: Multi-level testing including regression checks
- 📝 **Post-Mortem Reviews**: Extract learnings to prevent recurrence

## When to Use

**Use this skill when:**
- Problem cause is unclear and requires investigation
- A previous fix attempt failed
- Issue involves multiple components interacting
- Modifications carry risk or side effects
- You'd need to say "可能是..." to explain the cause

**Skip for:**
- Obvious one-liner fixes
- Clear error messages with known solutions
- User says "just fix it" for simple issues

## The Process

1. **Define**: Turn vague symptoms into precise problem statements
2. **Diagnose**: Trace data flow, verify each step, confirm root cause
3. **Design**: Generate and compare at least 2 solution candidates
4. **Execute**: Change one variable at a time with rollback plan
5. **Verify**: Reproduce trigger, check regressions, test durability
6. **Review**: Extract lessons for future prevention

## Installation

### Via ClawHub (Recommended)

```bash
clawhub install problem-solving
```

### Manual Installation

Clone to `~/.openclaw/skills/problem-solving`

## Usage

The skill activates automatically when appropriate. You can also explicitly request it:

```
帮我分析一下这个问题
Use structured problem solving for this issue
Let's diagnose this systematically
```

## Anti-Patterns to Avoid

- **Guess-and-fix**: See symptom → change immediately
- **Surface fix**: Change bad value without asking why
- **Multi-change**: Change 3 things at once
- **Premature victory**: "Should be fixed" without verification

## License

MIT License - see [LICENSE](LICENSE) file
````

## File: .gitignore
size: 35
sha: c3b31bfdaaa17963beb9a63abb69e0d8089bd2e1
upstream: https://github.com/lovensky1992-wk/problem-solving/blob/HEAD/.gitignore

```text
__pycache__/
*.pyc
*.pyo
.DS_Store
```

## File: LICENSE
size: 1078
sha: 4f92758656dd4e8c463b272113aa379154d19974
upstream: https://github.com/lovensky1992-wk/problem-solving/blob/HEAD/LICENSE

```text
MIT License

Copyright (c) 2026 OpenClaw Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
