debug-methodology

# Debug Methodology

Systematic approach to debugging and problem-solving. Distilled from real production incidents and industry best practices.

## ⚠️ The Root Cause Imperative

**Every fix MUST target the root cause. Workarounds are forbidden unless explicitly approved.**

Before proposing ANY solution, pass the Root Cause Gate:

```
┌─────────────────────────────────────────────┐
│            ROOT CAUSE GATE                  │
│                                             │
│  1. What is the ACTUAL problem?             │
│  2. WHY does it happen? (not just WHAT)     │
│  3. Does my fix eliminate the WHY?           │
│     YES → proceed                           │
│     NO  → this is a workaround → STOP       │
│                                             │
│  Workaround test:                           │
│  "If I remove my fix, does the bug return?" │
│     YES → workaround (fix the cause instead)│
│     NO  → genuine fix ✅                    │
└─────────────────────────────────────────────┘
```

### The 5 Whys — Mandatory for Non-Obvious Problems

```
Problem: API returns 524 timeout
  Why? → Cloudflare cuts connections >100s
  Why? → The API call takes >100s
  Why? → Using non-streaming request, server holds connection silent
  Why? → Code uses regular fetch, not streaming
  Fix: → Use streaming (server sends data continuously, Cloudflare won't cut)

  ❌ WRONG: Switch to faster model (workaround — avoids the timeout instead of fixing it)
  ✅ RIGHT: Use streaming API (root cause — Cloudflare needs ongoing data)
```

### Common Workaround Traps

| Problem | Workaround (❌) | Root Cause Fix (✅) |
|---------|----------------|-------------------|
| API timeout | Switch to faster model | Use streaming / fix the slow query |
| Data precision loss | Search by name instead of ID | Fix BigInt parsing |
| Search returns nothing | Try different search strategy | Fix the search implementation |
| Dependency conflict | Downgrade / pin version | Use correct environment (v...

# 🔍 Debug Methodology

[![ClawHub](https://img.shields.io/badge/ClawHub-debug--methodology-blue?style=flat-square)](https://clawhub.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Agent_Skill-orange?style=flat-square)](https://github.com/openclaw/openclaw)

**系统化调试方法论** — 适用于 AI Agent 和开发者的通用调试规范。

> 从真实生产事故中提炼，结合 Nicole Tietz、Brendan Gregg、Julia Evans 等业界顶级工程师的方法论。

## 为什么需要这个？

AI Agent 在调试时容易陷入以下陷阱：
- 🚨 **醉汉反模式** — 随机改代码直到问题消失
- 🚨 **路灯反模式** — 只在熟悉的地方找，而不是问题真正在的地方
- 🚨 **补丁链** — 每次报新错就修那个错，越改越乱
- 🚨 **忽略用户** — 用户说"改了X就坏了"，却继续自己猜

这套方法论提供了一个**强制性的调试流程**，避免这些常见错误。

## 核心流程

```
Phase 1: STOP    → 动手前先搞清现状（进程、环境、启动命令）
Phase 2: THINK   → 形成一个假设（优先查自己改了什么）
Phase 3: TEST    → 一次改一个，验证后再继续
Phase 4: DETECT  → 改了2次没好？全部回退，重新来
```

## 快速决策树

```
Error appears
  ├─ Was I just editing? → DIFF my changes → REVERT if suspect
  ├─ Service won't start? → CHECK startup command + environment
  ├─ New error after fix? → STOP (patch chain!) → Revert all → Phase 1
  ├─ User reports regression? → DIFF before/after their last known-good
  └─ Intermittent? → CHECK logs + external dependencies + timing
```

## 作为 OpenClaw Skill 使用

将 `SKILL.md` 放入你的 skills 目录：

```bash
mkdir -p ~/.agents/skills/debug-methodology
cp SKILL.md ~/.agents/skills/debug-methodology/
```

重启 OpenClaw 后，所有 session 遇到调试场景会自动加载这套方法论。

## 完整规范

详见 [SKILL.md](SKILL.md) — 包含：

- **4阶段调试流程**（STOP → Hypothesize → Test → Patch-Chain Detection）
- **4大反模式警告**（醉汉/路灯/货物崇拜/忽略用户）
- **环境检查清单**（runtime/deps/config/process manager/logs/backup）
- **部署安全流程**（拉取→备份→修改→测试→部署→验证）
- **...