| name | moai-essentials-debug |
| description | Advanced debugging with stack trace analysis, error pattern detection, and fix suggestions. Use when delivering quick diagnostic support for everyday issues. |
| allowed-tools | ["Read","Bash","Write","Edit","TodoWrite"] |
MoAI Essentials Debug v2.1
Skill Metadata
| Field | Value |
|---|
| Version | 2.1.0 |
| Created | 2025-10-22 |
| Last Updated | 2025-10-27 |
| Language Coverage | 23 languages + containers + distributed systems |
| Allowed tools | Read, Write, Edit, Bash, TodoWrite |
| Auto-load | On demand during Run stage (debug-helper) |
| Trigger cues | Runtime error triage, stack trace analysis, root cause investigation requests |
What it does
Comprehensive debugging support across all 23 MoAI-ADK languages with:
- Language-specific debugger integration
- Stack trace analysis and error pattern detection
- Container and Kubernetes debugging
- Distributed tracing with OpenTelemetry
- Cloud debugger integration (AWS X-Ray, GCP Cloud Debugger)
- Performance profiling with Prometheus
When to use
- Runtime errors, exceptions, crashes
- Stack trace analysis requests
- "Why is this failing?", "Debug this error"
- Container/K8s debugging scenarios
- Distributed system tracing
- Performance bottleneck investigation
- Automatically invoked via debug-helper sub-agent
Quick Reference: Debugger by Language
Systems Programming
- C/C++: gdb 14.x, lldb 17.x, AddressSanitizer
- Rust: rust-lldb, rust-gdb, RUST_BACKTRACE=1
- Go: Delve 1.22.x, goroutine debugging
JVM Ecosystem
- Java: jdb, IntelliJ IDEA, Remote JDWP
- Kotlin: IntelliJ Kotlin Debugger, Coroutines debugger
- Scala: IntelliJ Scala Plugin, sbt debug mode
- Clojure: CIDER, Cursive, REPL-based debugging
Scripting Languages
- Python: pdb, debugpy 1.8.0, pudb (TUI)
- Ruby: debug gem (built-in), byebug, pry-byebug
- PHP: Xdebug 3.3.x, phpdbg
- Lua: ZeroBrane Studio, MobDebug
- Shell: bash -x, set -x toggle
Web & Mobile
- JavaScript: Chrome DevTools, node --inspect
- TypeScript: Chrome DevTools with source maps, VS Code debugger
- Dart/Flutter: Flutter DevTools, hot reload
- Swift: LLDB (Xcode), Instruments profiling
Functional & Concurrency
- Haskell: GHCi debugger, Debug.Trace
- Elixir: IEx debugger, :observer.start()
- Julia: Debugger.jl, Infiltrator.jl
- R: browser(), debug(), RStudio debugger
Enterprise & Data
- C#: Visual Studio Debugger, Rider, vsdbg
- SQL: EXPLAIN ANALYZE, pg_stat_statements
Complete debugger matrix with CLI commands: See reference.md
Debugging Workflow (6-Step Process)
1. Reproduce
2. Isolate
3. Investigate
4. Hypothesize
5. Fix
6. Verify
Common Error Patterns by Language Category
Memory Safety
- C/C++: Buffer overflow, use-after-free, memory leaks
- Tools: Valgrind, AddressSanitizer (
-fsanitize=address)
- Rust: Ownership violations (prevented at compile time)
- Go: Goroutine leaks, improper channel usage
Null/Nil Handling
- Java: NullPointerException → Use Optional
- Kotlin: NullPointerException → Leverage null safety (?.)
- TypeScript: undefined access → Optional chaining (?.)
- Go: Nil pointer → Early nil checks
- Rust: Option unwrap → Pattern matching
Type Errors
- Python: TypeError, AttributeError → Type hints + mypy
- JavaScript: Type coercion bugs → Use TypeScript
- Ruby: NoMethodError → Duck typing checks
Concurrency Issues
- Go: Data races →
go build -race, proper channel usage
- Java: ConcurrentModificationException → Use concurrent collections
- Rust: Data races (prevented by borrow checker)
- Python: GIL limitations → Use multiprocessing for CPU-bound tasks
Async/Await Pitfalls
- Python:
RuntimeError: Event loop is closed → Proper asyncio usage
- JavaScript: Unhandled promise rejections → Always catch async errors
- Rust: Send/Sync trait violations → Understand thread safety
Detailed error pattern analysis: See examples.md
Container & Kubernetes Debugging
Docker Debugging
docker exec -it <container> /bin/sh
docker run -p 5005:5005 -e JAVA_TOOL_OPTIONS='-agentlib:jdwp=...' myapp
docker run -p 5678:5678 -e DEBUGPY_ENABLE=true myapp
Kubernetes Debugging
kubectl port-forward pod/myapp-pod 5005:5005
kubectl exec -it myapp-pod -- /bin/bash
kubectl debug -it myapp-pod --image=busybox --target=myapp
Complete container debugging guide: See reference.md
Distributed Tracing
OpenTelemetry 1.24.0+
- Python: opentelemetry-api, opentelemetry-sdk
- TypeScript: @opentelemetry/sdk-trace-node
- Exporters: Jaeger, Zipkin, OTLP
Prometheus 2.48.x Integration
- Metrics: Counter, Gauge, Histogram, Summary
- Python: prometheus-client 0.19.0
- Go: prometheus/client_golang
Cloud Debuggers
- AWS X-Ray: aws-xray-sdk, auto-instrumentation
- GCP Cloud Debugger: googleclouddebugger Python package
Complete distributed tracing setup: See reference.md
Stack Trace Analysis Quick Guide
Reading Stack Traces
Direction: Bottom (entry point) → Top (error site)
Key information:
- 📍 Location: File and line number
- 🔍 Context: Function name and arguments
- 💡 Error type: Exception class or error message
Analysis Pattern
- Identify error type: What exception/error?
- Locate error site: Top of stack trace
- Trace execution path: Follow stack from bottom
- Identify root cause: Where did bad data/state originate?
- Suggest fix: 1-3 actionable options
Language-specific stack trace examples: See examples.md
Performance Profiling Integration
CPU Profiling
- Python: cProfile, py-spy (production-safe)
- Go: pprof, go test -cpuprofile
- Rust: flamegraph crate
- Java: Java Flight Recorder (JFR)
Memory Profiling
- Python: memory_profiler, tracemalloc
- Go: pprof memory profiling
- C/C++: Valgrind massif
- Rust: heaptrack
Complete profiling guide: See reference.md
Inputs
- Stack traces, error messages, logs
- Code context (relevant files)
- Environment information (versions, config)
- Reproduction steps
Outputs
- Root cause analysis with evidence
- Actionable fix suggestions (1-3 options)
- Debugging checklist tailored to error type
- Code snippets demonstrating fix
Failure Modes
- Insufficient stack trace or log information
- Unable to reproduce error locally
- Complex distributed system failures requiring multi-service tracing
- Race conditions or timing-dependent bugs
Dependencies
- Works with: tdd-implementer, debug-helper, quality-gate
- Requires: Language-specific debugger tools installed
- Optional: OpenTelemetry, Prometheus, cloud debugger SDKs
Related Skills
- moai-essentials-refactor (clean up code after debugging)
- moai-essentials-perf (performance bottleneck investigation)
- moai-alfred-debugger-pro (advanced debugging strategies)
- moai-foundation-trust (ensure debugging doesn't skip tests)
Best Practices
- Always create regression test after fixing bug (TDD cycle)
- Log debugging insights in code comments with @TAG references
- Use language-appropriate debugger (don't force Python workflow on Go)
- Enable source maps for compiled/transpiled languages
- Set up distributed tracing early in microservices projects
- Use production-safe profilers (py-spy, async-profiler) in live systems
- Document reproduction steps in issue tracker or SPEC HISTORY
For complete 23-language debugger matrix: reference.md
For language-specific debugging examples: examples.md
End of Skill | Refactored 2025-10-27
