/debug

allowed-tools: Task, Read, Write, Edit, Bash(rg:*), Bash(fd:*), Bash(bat:*), Bash(eza:*), Bash(jq:*), Bash(gdate:*), Bash(git:*), Bash(docker:*), Bash(kubectl:*), Bash(ps:*), Bash(netstat:*), Bash(lsof:*), Bash(strace:*), Bash(gdb:*), Bash(lldb:*), Bash(jstack:*), Bash(jcmd:*), Bash(delve:*), Bash(go:*), Bash(cargo:*), Bash(mvn:*), Bash(gradle:*), Bash(deno:*)
name: "Debug"
description: "Systematic debugging orchestrator with multi-language support and intelligent root cause analysis"
author: "wcygan"
tags: ["test","debug"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N 2>/dev/null || date +%s%N 2>/dev/null || echo "$(date +%s)$(jot -r 1 100000 999999 2>/dev/null || shuf -i 100000-999999 -n 1 2>/dev/null || echo $RANDOM$RANDOM)"`
• Debug target: $ARGUMENTS
• Current directory: !`pwd`
• Project structure: !`eza -la --tree --level=2 2>/dev/null | head -10 || fd . -t d -d 2 | head -8`
• Build files detected: !`fd "(package\.json|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|deno\.json)" . -d 3 | head -5 || echo "No build files detected"`
• Git status: !`git status --porcelain 2>/dev/null | head -5 || echo "No git repository"`
• Recent commits: !`git log --oneline -3 2>/dev/null || echo "No git history"`
• Running processes: !`ps aux | rg -E "(java|go|rust|deno|node)" | head -3 2>/dev/null || echo "No relevant processes found"`
• System logs (recent): !`tail -5 /var/log/system.log 2>/dev/null || dmesg | tail -3 2>/dev/null || echo "System logs unavailable"`

Your Task

STEP 1: Initialize systematic debugging session with intelligent issue classification

• CREATE session state file: `/tmp/debug-session-$SESSION_ID.json`
• ANALYZE issue description from Context section for patterns
• CLASSIFY debug target type (error message, performance issue, crash, etc.)
• DETECT project technology stack and select appropriate debugging tools

# Initialize debugging session state
echo '{
  "sessionId": "'$SESSION_ID'",
  "debugTarget": "'$ARGUMENTS'",
  "issueType": "auto-detect",
  "technologyStack": [],
  "debugStrategy": "systematic",
  "findings": [],
  "recommendedActions": []
}' > /tmp/debug-session-$SESSION_ID.json

STEP 2: Multi-phase debugging analysis with parallel sub-agent coordination

TRY:

IF issue_complexity == "complex_system_issue" OR technology_stack == "multi-service":

LAUNCH parallel sub-agents for comprehensive debugging analysis:

• **Agent 1: Error Analysis**: Parse and analyze error messages, stack traces, and logs
• Focus: Error patterns, stack trace analysis, log correlation, exception chains
• Tools: rg for log parsing, language-specific stack trace analyzers
• Output: Root cause candidates with confidence scores

• **Agent 2: Code Path Analysis**: Trace execution flow and identify potential failure points
• Focus: Function calls, variable states, control flow, recent code changes
• Tools: rg for code search, git for change analysis, static analysis
• Output: Execution timeline and state analysis

• **Agent 3: Environment Analysis**: Examine runtime environment and system state
• Focus: Dependencies, configuration, resource usage, external services
• Tools: docker, kubectl, ps, netstat for system state analysis
• Output: Environmental factors and configuration issues

• **Agent 4: Historical Analysis**: Review recent changes and deployment history
• Focus: Git history, deployment logs, configuration changes
• Tools: git log, docker history, configuration diff analysis
• Output: Change correlation and regression analysis

ELSE:

EXECUTE streamlined single-service debugging workflow:

# Direct debugging analysis for simpler issues
echo "🔍 Executing focused debugging analysis..."

STEP 3: Technology-specific debugging strategy execution TRY:

CASE detected_technology: WHEN "java":

# Java-specific debugging workflow
echo "☕ Java debugging strategy activated"

# Check for running Java processes
jps -v || ps aux | rg java

# Generate thread dump if process found
if jstack_pid=$(jps | rg -v Jps | head -1 | cut -d' ' -f1); then
  echo "Generating thread dump for PID: $jstack_pid"
  jstack $jstack_pid > /tmp/threaddump-$SESSION_ID.txt
fi

# Check JVM flags and heap usage
jcmd $jstack_pid VM.flags 2>/dev/null || echo "JVM flags unavailable"
jcmd $jstack_pid GC.run_finalization 2>/dev/null || echo "GC info unavailable"

**Java Debugging Actions:**

• Remote debugging with JDWP: `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005`
• Conditional breakpoints in IDE with expression evaluation
• JVM diagnostic flags: `-XX:+PrintGCDetails -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/`
• Thread dumps and heap analysis with jstack, jcmd, jhat
• Flight Recorder: `-XX:+UnlockCommercialFeatures -XX:+FlightRecorder`

WHEN "go":

# Go-specific debugging workflow
echo "🐹 Go debugging strategy activated"

# Check for Go binaries and build info
fd -e go . | head -5
go version 2>/dev/null || echo "Go not available"

# Check for race conditions in recent builds
if [ -f "go.mod" ]; then
  echo "Checking for recent race detector usage..."
  rg "go run -race|go test -race" . || echo "No race detection usage found"
fi

# Check for goroutine leaks in running processes
ps aux | rg go | head -3

**Go Debugging Actions:**

• Delve debugger: `dlv debug ./main.go` or `dlv attach <pid>`
• pprof for runtime analysis: `go tool pprof http://localhost:6060/debug/pprof/heap`
• Race detector: `go run -race main.go` or `go test -race ./...`
• Structured logging with context: `log/slog` with contextual fields
• Goroutine analysis: `go tool pprof http://localhost:6060/debug/pprof/goroutine`

WHEN "rust":

# Rust-specific debugging workflow
echo "🦀 Rust debugging strategy activated"

# Check Cargo configuration and recent builds
fd Cargo.toml . | head -3
cargo --version 2>/dev/null || echo "Cargo not available"

# Set backtrace envi