moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-essentials-debug/SKILL.md

@@ -1,303 +0,0 @@
----
-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](reference.md)
-
----
-
-## Debugging Workflow (6-Step Process)
-
-### 1. Reproduce
-- [ ] Minimal reproducible example (MRE)
-- [ ] Consistent reproduction steps
-- [ ] Document environment (OS, language version, dependencies)
-
-### 2. Isolate
-- [ ] Binary search the code (comment out sections)
-- [ ] Check recent changes (git diff, git log)
-- [ ] Verify input data and edge cases
-
-### 3. Investigate
-- [ ] Read stack trace from bottom (entry point) to top (error site)
-- [ ] Add logging at key decision points
-- [ ] Use debugger breakpoints before error location
-- [ ] Check variable state in debugger
-
-### 4. Hypothesize
-- [ ] Form theory about root cause
-- [ ] Identify 2-3 most likely culprits
-- [ ] Design experiment to test hypothesis
-
-### 5. Fix
-- [ ] Implement minimal fix first
-- [ ] Add regression test (RED → GREEN)
-- [ ] Refactor if needed (REFACTOR stage)
-- [ ] Update documentation
-
-### 6. Verify
-- [ ] Run full test suite
-- [ ] Test edge cases explicitly
-- [ ] Verify fix in production-like environment
-- [ ] Monitor for recurrence
-
----
-
-## 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<T>
-- **Kotlin**: NullPointerException → Leverage null safety (?.)
-- **TypeScript**: undefined access → Optional chaining (?.)
-- **Go**: Nil pointer → Early nil checks
-- **Rust**: Option<T> 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](examples.md)
-
----
-
-## Container & Kubernetes Debugging
-
-### Docker Debugging
-```bash
-# Attach to running container
-docker exec -it <container> /bin/sh
-
-# Debug with debugger ports exposed
-docker run -p 5005:5005 -e JAVA_TOOL_OPTIONS='-agentlib:jdwp=...' myapp
-
-# Python remote debugging
-docker run -p 5678:5678 -e DEBUGPY_ENABLE=true myapp
-```
-
-### Kubernetes Debugging
-```bash
-# Port-forward debugger port
-kubectl port-forward pod/myapp-pod 5005:5005
-
-# Exec into pod
-kubectl exec -it myapp-pod -- /bin/bash
-
-# Debug with ephemeral container (K8s 1.23+)
-kubectl debug -it myapp-pod --image=busybox --target=myapp
-```
-
-> **Complete container debugging guide**: See [reference.md](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](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
-
-1. **Identify error type**: What exception/error?
-2. **Locate error site**: Top of stack trace
-3. **Trace execution path**: Follow stack from bottom
-4. **Identify root cause**: Where did bad data/state originate?
-5. **Suggest fix**: 1-3 actionable options
-
-> **Language-specific stack trace examples**: See [examples.md](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](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](reference.md)  
-**For language-specific debugging examples**: [examples.md](examples.md)
-
----
-
-**End of Skill** | Refactored 2025-10-27