errors skill

---
name: errors
license: MIT
compatibility: "Claude Code 2.1.34+. Requires memory MCP server."
description: Error pattern analysis and troubleshooting for Claude Code sessions. Use when handling errors, fixing failures, troubleshooting issues.
context: inherit
agent: debug-investigator
version: 1.0.0
author: OrchestKit
tags: [errors, debugging, troubleshooting, patterns]
user-invocable: false
allowed-tools: [Read, Bash, Grep]
complexity: low
metadata:
  category: document-asset-creation
  mcp-server: memory
---

# Error Pattern Analysis

Analyze errors captured from Claude Code sessions to identify patterns and get actionable insights.

## Quick Start

```bash
/errors              # Batch analysis of historical error patterns
/debug               # CC 2.1.30 real-time debug for current session
```

### When to Use Which

| Command | Purpose | Scope |
|---------|---------|-------|
| `/errors` | Batch analysis of error patterns (last 24h/7d) | Historical patterns |
| `/debug` | Real-time debug of current session state | Current session |
| `/ork:fix-issue` | Full RCA workflow for specific bug | Single issue |

## Quick Analysis

```bash
# Run batch analysis on last 24h of errors
python .claude/scripts/analyze_errors.py

# Analyze last 7 days
python .claude/scripts/analyze_errors.py --days 7

# Generate markdown report
python .claude/scripts/analyze_errors.py --report
```

## What Gets Captured

The error collector hook captures:
- Tool name (Bash, mcp__memory__search_nodes, etc.)
- Error message (first 500 chars)
- Tool input (command/query that failed)
- Timestamp and session ID

**Location:** `.claude/logs/errors.jsonl`

## Current Error Rules

Check learned patterns that trigger warnings:

```bash
cat .claude/rules/error_rules.json | jq '.rules[] | {id, signature, count: .occurrence_count}'
```

## Files

| File | Purpose |
|------|---------|
| `.claude/hooks/posttool/error-collector.sh` | Captures errors to JSONL |
| `.claude/hooks/pretool/bash/error-pattern-warner.sh` | Warns before risky commands |
| `.claude/scripts/analyze_errors.py` | Batch pattern analysis |
| `.claude/rules/error_rules.json` | Learned error patterns |
| `.claude/logs/errors.jsonl` | Raw error log |

## Common Patterns

### PostgreSQL Connection Errors

```
pattern: role "X" does not exist
fix: Use Docker connection: docker exec -it orchestkit-postgres-dev psql -U orchestkit_user -d orchestkit_dev

pattern: relation "X" does not exist
fix: Check MCP postgres server connection string - may be connected to wrong database
```

## Related Skills
- fix-issue: Fix identified errors
- debug-investigator: Debug error root causes
## Adding New Rules

Rules are auto-generated by `analyze_errors.py` when patterns repeat 2+ times.
For manual rules, edit `.claude/rules/error_rules.json`:

```json
{
  "id": "custom-001",
  "pattern": "your regex pattern",
  "signature": "human readable signature",
  "tool": "Bash",
  "occurrence_count": 1,
  "fix_suggestion": "How to fix this"
}
```