debug

name	debug
description	Debug and fix issues with structured analysis (Debugger Agent)

🐛 DEBUGGER AGENT

Debug issue:

Issue: {{args}}

MODE DETECTION

Mode	Trigger	Features
API	"500", "error", "response", "endpoint"	Root cause, fix, rollback
DB	"connection", "pool", "query", "timeout"	Leak detection, kill commands
CI	"ci", "actions", "pipeline", "build"	Workflow analysis, fix
PERF	"slow", "latency", "performance", "degradation"	N+1, EXPLAIN, optimization
GENERAL	default	Standard debug flow

---

DEBUG REPORT FORMAT (Runbook)

📋 Issue Summary

• Symptom: [What's happening]
• Started: [When/after what change]
• Severity: Critical / High / Medium / Low
• Affected: [Users, services, endpoints]

---

🔍 Investigation

Logs Analysis

[Key error logs]

Recent Changes

• [Deploy/commit that may have caused this]
• [Config changes]
• [Dependency updates]

---

🎯 Root Cause

[Clear explanation of why this is happening]

---

🔧 Fix Plan

Step 1: [Immediate mitigation]

# Command to run

Step 2: [Code fix]

// Before
[broken code]

// After
[fixed code]

Step 3: [Validation]

# Test the fix

---

⏪ Rollback Steps

If fix doesn't work:

1. [Rollback step 1]
2. [Rollback step 2]

# Rollback command
git revert [commit]
# or
kubectl rollout undo deployment/[name]

---

✅ Validation Commands

# Verify fix worked
curl -X POST https://api.example.com/endpoint
# Expected: 200 OK

# Check logs
tail -f /var/log/app.log | grep ERROR
# Expected: No new errors

# Monitor metrics
# Expected: Error rate < 0.1%

---

🛡️ Prevention

To prevent this in future:

• Add test case for this scenario
• Add monitoring alert
• Update documentation
• Add input validation

---

MODE-SPECIFIC SECTIONS

API MODE (500 Errors)

• Request/Response analysis
• Auth validation
• Middleware chain trace
• Connection pool status

DB MODE (Connection Issues)

-- Active connections
SELECT * FROM pg_stat_activity;

-- Long running queries
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;

-- Kill stuck query
SELECT pg_terminate_backend(pid);

CI MODE (Pipeline Failures)

• Workflow file analysis
• Dependency check
• Cache invalidation
• Environment variables

PERF MODE (Performance)

-- EXPLAIN ANALYZE
EXPLAIN ANALYZE SELECT ...;

• N+1 query detection
• Missing index identification
• Memory/CPU profiling

---

PRO TIPS

• Collect context first - errors, timestamps, recent deploys
• Check usual suspects - deploys, config, migrations
• Validate in staging - test fix before prod
• Save as runbook - reuse for similar issues

Key Takeaway: Turns hours of troubleshooting into 30-minute structured analysis.