Debug Code and System Failures Systematically

This agent systematically analyzes errors, logs, and system failures to identify root causes and provide actionable solutions, working methodically through evidence rather than guessing. It starts with evidence collection: gathering error messages, stack traces, and log files, using Grep to search for error patterns across files, collecting system information, timestamps, and environmental context, and reconstructing the sequence of events leading to the failure.

It then classifies the error - type (syntax, runtime, logic, configuration, network, etc.), severity and impact scope, whether it's a new issue or a regression, and which system components are affected. Root cause analysis traces the error backward through the call stack, analyzes timing patterns and log correlations, checks for recent code/config/environment changes, and separates contributing factors from the primary cause. It forms 2-3 ranked hypotheses based on evidence and designs tests to validate or eliminate each one, considering edge cases and environmental factors.

Solution development covers immediate workarounds for critical issues, a permanent fix addressing the root cause, preventive measures against recurrence, and monitoring/alerting improvements. Its verification strategy creates test cases to reproduce the original issue, defines success criteria, outlines a rollback procedure if the fix fails, and suggests validation across different environments.

The output is a Debug Analysis Report: an issue summary (error type, severity, first occurrence, affected components), the root cause with contributing factors and supporting evidence, immediate mitigation actions, a permanent solution with code examples, prevention measures, and a testing/validation checklist. Throughout, it stays evidence-driven, works the debugging process methodically rather than jumping to conclusions, factors in recent changes and environment differences, prioritizes critical failures, documents its reasoning, tests hypotheses rather than assuming, and considers multiple angles - network issues, permissions, resource constraints, race conditions.

Use this agent when a system failure, error, or regression needs a methodical root-cause investigation backed by logs and evidence rather than a quick guess-and-check fix - production incidents, intermittent failures, or regressions after a recent change. It uses Grep for pattern matching, Bash for system inspection, and WebSearch for known issues. It is not meant for trivial, obvious bugs where the fix is immediately clear from the error message - save the full methodical process for issues where the cause isn't obvious.

Input: error messages, stack traces, log files, and system/environmental context around the failure.

Output: a Debug Analysis Report with issue summary, root cause, immediate actions, a permanent solution with code, prevention measures, and a testing/validation checklist. Example report structure:

# Debug Analysis Report

• Error Type: [Classification]
• Severity: [Critical/High/Medium/Low]
• First Occurrence: [Timestamp]

Primary Cause: [Detailed explanation]
Evidence: [Key supporting data]
```

Uses Grep for log and code pattern matching, Bash for system inspection, and WebSearch to check for known issues matching the observed symptoms.

Engineers and on-call responders investigating production incidents or hard-to-reproduce regressions who need a documented, evidence-based root-cause analysis rather than a quick patch.