debugging and troubleshooting

🐛 Debugging and Troubleshooting

Version: 2.0.0 Last Updated: 2025-11-22 Priority: ⭐⭐⭐⭐ (P1 Level) Purpose: Systematic Error Diagnosis and Rust Debugging Workflow

---

📋 Overview

Provides a systematic diagnosis and resolution workflow for compilation errors, test failures, and runtime errors.

---

🎯 P0: Invocation Triggers

Trigger	Example
Malfunction	"this code isn't working"
Test failure	"why is this test failing?"
Error analysis	"debug this error"
Compilation error	"compilation error"
Runtime error	"runtime panic"

---

🔧 P1: Error Classification and Handling

Error Classification Table

Classification	Symptom	Diagnostic command	Priority
Compilation error	error[E####]	cargo check	High
Test failure	test ... FAILED	cargo test -- --nocapture	High
Runtime panic	thread 'main' panicked	RUST_BACKTRACE=1	High
Logic error	Output differs from expectation	dbg!(), logs	Medium
Performance	Slow / high memory	cargo bench, valgrind	Medium
Integration error	External service failure	Network diagnostics	Low

---

🚀 P2: Debugging Patterns

Pattern 1: Compilation Errors

# Step 1: エラー確認
cargo check 2>&1 | head -50

# Step 2: エラーコード解析
# error[E0277] → Trait未実装
# error[E0412] → 型未定義
# error[E0433] → モジュール未解決

# Step 3: 詳細情報
rustc --explain E0277

Common errors and solutions:

Error code	Cause	Solution
E0277	Trait not implemented	#[derive(...)] or manual implementation
E0412	Type not found	usestatement added
E0433	Module resolution failure	Check path,moddeclaration
E0502	Borrow conflict	Review borrow scope
E0382	Use after ownership move	clone() or reference

Pattern 2: Test Failures

# Step 1: 失敗テスト特定
cargo test 2>&1 | grep FAILED

# Step 2: 詳細出力で実行
cargo test test_name -- --nocapture

# Step 3: 順次実行（並列問題回避）
cargo test -- --test-threads=1

# Step 4: アサーション詳細
# pretty_assertions, insta使用推奨

Pattern 3: Runtime Panics

# Step 1: バックトレース取得
RUST_BACKTRACE=1 cargo run

# Step 2: 完全バックトレース
RUST_BACKTRACE=full cargo run

# Step 3: panic箇所特定
# at src/lib.rs:42:5 を確認

# Step 4: デバッガ使用
rust-lldb target/debug/miyabi

Pattern 4: Logic Errors

// dbg!マクロ使用
let result = dbg!(compute_value());

// tracing使用
tracing::debug!(?value, "computed value");

// 条件付きログ
if cfg!(debug_assertions) {
    println!("Debug: {:?}", state);
}

---

⚡ P3: Advanced Debugging Tools

Debugging Tools List

Tool	Purpose	Command
rust-lldb	Debugger	rust-lldb target/debug/miyabi
cargo-expand	Macro expansion	cargo expand
cargo-asm	Assembly inspection	cargo asm
valgrind	Memory diagnostics	valgrind ./target/debug/miyabi
miri	UB detection	cargo +nightly miri test

VS Code Debug Configuration

{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Miyabi",
  "cargo": {
    "args": ["build", "--bin=miyabi"]
  },
  "args": [],
  "cwd": "${workspaceFolder}"
}

---

🛡️ Common Panic Handling

Panic	Cause	Handling
unwrap() on None	Unhandled Option	if let Some / ?
unwrap() on Err	Unhandled Result	match / ?
index out of bounds	Array index out of bounds	.get() / bounds check
overflow	Arithmetic overflow	checked_* / wrapping_*
stack overflow	Infinite recursion	Review recursion logic

---

✅ Success Criteria

Check item	Criteria
Error classification	Accurate classification
Root cause identification	Cause clarified
Solution presentation	Specific fix method
Prevention of recurrence	Add test

---

🔗 Related Skills

• Rust Development: Build/Test
• Performance Analysis: Performance issue
• Security Audit: Security issue