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：深刻度を評価する

深刻度のレベル

レベル	説明	例
重大	システムが使用不能、データに危険が及ぶ	ビルドが完全に壊れている、テストによってデータが失われる
大	主要な機能が壊れている	機能が動作しない、多数のテストが失敗する
軽微	限定的な問題で、回避策がある	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│   │     │     │     │     │     │
  └────┘   └────┘      └────┘      └────┘

コードエラーからの復旧

1 つのファイルが壊れている場合：

# 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 によるイシューの更新