Analyze errors, stack traces, and logs to identify root causes and recommend fixes
Analyzes errors, logs, and stack traces to identify root causes, recommend fixes, and automatically creates prioritized todo files for implementation.
When to use
Use this when you encounter a runtime error, need to understand a system failure, or want to systematically document and plan fixes for a bug.
How to invoke
Both: manual via /debug, or auto-invoked when Claude detects error logs or stack traces.
npx claudepluginhub jayteealao/agent-skills[optional: error description or paste error logs]Systematically analyze errors, stack traces, and logs to identify root causes and implement fixes.
# Analyze inline error
/debug "TypeError: Cannot read property 'id' of undefined"
# Analyze with stack trace
/debug "
Error: Connection refused
at Database.connect (src/db/connection.ts:23)
at async initialize (src/server.ts:45)
"
# Analyze log file
/debug logs/application.log
# Interactive mode (will prompt for details)
/debug
The todo files created in Phase 4 are the output - no separate tracking needed.
5-phase workflow:
.claude/todos/Output: Todo files using file-todos skill format
Each action item becomes a todo file:
{id}-ready-p1-{description}.md{id}-ready-p2-{description}.md{id}-pending-p3-{description}.mdIf arguments provided ($ARGUMENTS):
If no arguments:
Use AskUserQuestion to gather error context:
questions:
- question: "How frequently does this error occur?"
header: "Frequency"
multiSelect: false
options:
- label: "One-time occurrence"
description: "Error happened once, cannot reproduce. May be transient issue."
- label: "Intermittent (rare)"
description: "Happens occasionally, hard to predict. Likely race condition or edge case."
- label: "Recurring (daily)"
description: "Happens regularly under specific conditions. Consistent pattern exists."
- label: "Constant (blocking)"
description: "Happens every time, blocking development. Critical issue."
- question: "What environment is affected?"
header: "Environment"
multiSelect: true
options:
- label: "Production"
description: "Affecting live users or deployed service"
- label: "Staging"
description: "Caught in pre-production"
- label: "Development"
description: "Only seen locally"
Then prompt for additional details:
Analysis depth based on frequency:
Default: If no answer provided, assume "Recurring (daily)"
Perform systematic error analysis using the error-analysis skill:
Error Classification
Root Cause Analysis
Codebase Investigation
.claude/solutions/ for similar previously-solved issuesFormat findings as a structured report:
# Error Analysis Report
## Summary
[Brief description of error and impact]
**Error Type:** [Type]
**Severity:** Critical / High / Medium / Low
**Status:** Root cause identified
---
## Error Details
**Message:** [Error message]
**Location:** [file:line]
**Stack Trace:**
[Stack trace]
**Context:**
- Environment: [env]
- Frequency: [occurrences]
---
## Root Cause Analysis
### Hypotheses Evaluated
1. **[Hypothesis 1]**
- Evidence: [Evidence]
- Result: [Confirmed/Rejected]
### Confirmed Root Cause
[Detailed explanation of root cause]
---
## Fix Recommendations
### Immediate Fix (Hotfix)
**File:** `[file_path:line]`
```[language]
// Before
[old code]
// After
[new code]
### Phase 4: Auto-Create Todos for Fixes
After presenting the analysis report, automatically create todo files in `.claude/todos/` for all action items:
For each action item:
- **Immediate actions** -> Create as `{id}-ready-p1-{description}.md` (Priority 1, ready to work)
- **Short-term actions** -> Create as `{id}-ready-p2-{description}.md` (Priority 2)
- **Long-term actions** -> Create as `{id}-pending-p3-{description}.md` (Priority 3, needs planning)
**Todo file format:** (use file-todos skill patterns)
```yaml
---
status: ready # or pending for long-term items
priority: p1 # p1 (immediate), p2 (short-term), p3 (long-term)
issue_id: "042"
tags: [bug-fix, error-handling]
dependencies: []
---
# [Action Item Title]
## Problem Statement
[From error analysis - the root cause]
## Proposed Solution
[From fix recommendations]
## Technical Details
- **Affected Files**: [Files from analysis]
- **Effort**: [Small/Medium/Large]
- **Risk**: [Low/Medium/High]
## Acceptance Criteria
- [ ] Fix implemented as specified
- [ ] Tests added to prevent regression
- [ ] Verified in development environment
- [ ] No regressions introduced
## Work Log
### [Date] - Created from Debug Session
**Source:** `/debug` command analysis
**Root Cause:** [Brief root cause]
**Priority Rationale:** [Why this priority]
Determine next issue ID:
# Find highest issue ID in .claude/todos/
ls .claude/todos/ 2>/dev/null | grep -E '^[0-9]+' | sed 's/-.*$//' | sort -n | tail -1
# Increment by 1 for each new todo
Present final summary:
## Debug Session Complete
**Error:** [Brief error description]
**Root Cause:** [Root cause in one sentence]
**Fix Status:** Recommendations provided and todos created
---
### Todos Created
**Total:** [X] todos created in `.claude/todos/`
**By Priority:**
- P1 (Immediate): [count] todos
- P2 (Short-term): [count] todos
- P3 (Long-term): [count] todos
### Next Steps
1. Apply hotfix: [file:line]
2. Run `/triage` to review and prioritize todos
This command integrates with:
allowed-tools)