error-recovery

错误恢复

概述

使用结构化恢复流程，妥善处理故障。

核心原则： 出现问题时不要慌。评估、保留、恢复、验证。

开始时声明：“我正在使用 error-recovery 处理此故障。”

恢复流程

Error Detected
      │
      ▼
┌─────────────┐
│ 1. ASSESS   │ ← Severity? Scope? Impact?
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 2. PRESERVE │ ← Capture evidence before it's lost
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 3. RECOVER  │ ← Follow decision tree
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 4. VERIFY   │ ← Confirm clean state
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 5. DOCUMENT │ ← Record what happened
└─────────────┘

第 1 步：评估严重程度

严重程度级别

级别	描述	示例
严重	系统无法使用，数据面临风险	构建完全损坏，测试导致数据丢失
重大	重要功能损坏	功能无法使用，大量测试失败
轻微	个别问题，有临时解决办法	单个测试不稳定，样式错误
信息	仅有警告，不影响使用	弃用通知，性能提示

评估问题

## Error Assessment

**Error:** [Description of error]
**Location:** [Where it occurred]

### Severity Checklist
- [ ] Is the system still functional?
- [ ] Is any data at risk?
- [ ] Are other features affected?
- [ ] Is this blocking progress?

### Scope
- Files affected: [list]
- Features affected: [list]
- Users affected: [none/some/all]

第 2 步：保留证据

尝试修复前先捕获证据：

错误日志

# Capture error output
pnpm test 2>&1 | tee error-log.txt

# Or from failed command
./failing-command 2>&1 | tee error-log.txt

堆栈跟踪

## Stack Trace

Error: Connection refused at Database.connect (src/db/connection.ts:45) at UserService.init (src/services/user.ts:23) at main (src/index.ts:12)

状态捕获

# Git state
git status
git diff

# Environment state
env | grep -E "NODE|NPM|PATH"

# Dependency state
pnpm list

截图（如涉及视觉问题）

对于 UI 错误，请在更改前截取屏幕截图。

第 3 步：恢复

决策树

What type of failure?
         │
    ┌────┴────┬────────────┬────────────┐
    │         │            │            │
  Code      Build      Environment   External
  Error     Error        Issue       Service
    │         │            │            │
    ▼         ▼            ▼            ▼
  ┌────┐   ┌────┐      ┌────┐      ┌────┐
  │Git │   │Clean│     │Re-  │     │Wait/│
  │reco│   │build│     │init │     │Retry│
  │very│   │     │     │     │     │     │
  └────┘   └────┘      └────┘      └────┘

代码错误恢复

单个文件损坏：

# Revert just that file
git checkout HEAD -- path/to/file.ts

功能损坏（涉及多个文件）：

# Find last good commit
git log --oneline

# Revert to that commit (soft reset keeps changes staged)
git reset --soft [GOOD_COMMIT]

# Or hard reset (discards changes)
git reset --hard [GOOD_COMMIT]

工作目录一团糟：

# Stash current changes
git stash

# Verify clean state
git status

# Optionally recover stash later
git stash pop

构建错误恢复

# Clean build artifacts
rm -rf node_modules dist build .cache

# Reinstall dependencies
pnpm install --frozen-lockfile  # Clean install from lock file

# Rebuild
pnpm build

环境错误恢复

# Check environment
env | grep -E "NODE|PNPM"

# Reset Node modules
rm -rf node_modules
pnpm install --frozen-lockfile

# If using nvm, verify version
nvm use

# Re-run init script
./scripts/init.sh

外部服务错误

# Check if service is up
curl -I https://service.example.com/health

# If down, wait and retry
sleep 60
curl -I https://service.example.com/health

# If still down, check status page
# Document as external blocker

第 4 步：验证

恢复后，验证状态是否正常：

基本验证

# Clean working directory
git status
# Expected: "nothing to commit, working tree clean" or known changes

# Tests pass
pnpm test

# Build succeeds
pnpm build

# Types check
pnpm typecheck

功能验证

# Run the specific thing that was broken
pnpm test --grep "specific test"

# Or verify the feature manually

第 5 步：记录

问题评论

gh issue comment [ISSUE_NUMBER] --body "## Error Recovery

**Error encountered:** [Description]

**Severity:** Major

**Evidence:**
\`\`\`
[Error output]
\`\`\`

**Recovery actions:**
1. [Action 1]
2. [Action 2]

**Verification:**
- [x] Tests pass
- [x] Build succeeds

**Root cause:** [If known]

**Prevention:** [If applicable]
"

知识图谱

// Store for future reference
mcp__memory__add_observations({
  observations: [{
    entityName: "Issue #[NUMBER]",
    contents: [
      "Encountered [error type] on [date]",
      "Caused by: [root cause]",
      "Resolved by: [recovery action]"
    ]
  }]
});

常见恢复模式

“测试之前通过，现在却失败了”

# What changed?
git diff HEAD~3

# Did dependencies change?
git diff HEAD~3 pnpm-lock.yaml

# Clean reinstall
rm -rf node_modules && pnpm install --frozen-lockfile

“本地运行正常，在 CI 中却失败了”

# Check for environment differences
# - Node version
# - OS differences
# - Env vars

# Run with CI-like settings
CI=true pnpm test

“构建之前正常，现在却损坏了”

# Check TypeScript errors
pnpm typecheck

# Check for circular dependencies
pnpm dlx madge --circular src/

# Clean build
rm -rf dist && pnpm build

“我把一切都搞砸了”

# Don't panic
# Find last known good state
git log --oneline

# Reset to that state
git reset --hard [GOOD_COMMIT]

# Verify
pnpm test

# Start again more carefully

升级处理

如果尝试 2-3 次后仍无法恢复：

## Escalation: Unrecoverable Error

**Issue:** #[NUMBER]

**Error:** [Description]

**Recovery attempts:**
1. [Attempt 1] - [Result]
2. [Attempt 2] - [Result]

**Current state:** [Broken/Partially working]

**Evidence preserved:** [Links to logs, screenshots]

**Requesting help with:** [Specific question]

将问题标记为 Blocked，并等待人工输入。

检查清单

发生错误时：

• 已评估严重程度
• 已保留证据（日志、状态、屏幕截图）
• 已选择恢复操作
• 已执行恢复
• 已验证状态正常
• 测试通过
• 构建成功
• 已记录问题

集成

此技能由以下项目调用：

• issue-driven-development - 发生错误时
• ci-monitoring - CI 失败时

此技能可能触发：

• research-after-failure - 原因未知时
• 通过 issue-lifecycle 更新问题