cfn-error-management

name	cfn-error-management
description	Unified error handling, batching, and logging for CFN Loop. Use when you need to capture agent errors, batch multiple errors for processing, log structured error data, or categorize and recover from agent failures.
version	1.0.0
tags	["mega-skill","errors","logging","batch-processing"]
status	production

Error Management Skill (Mega-Skill)

Version: 1.0.0 Purpose: Unified error handling, batching, and logging Status: Production Consolidates: cfn-standardized-error-handling, cfn-error-batching-strategy, cfn-error-logging

---

Overview

This mega-skill provides complete error management:

• Capture - Standardized error capture and categorization
• Batching - Error grouping for batch agent processing
• Logging - Error log storage and retrieval

---

Directory Structure

error-management/
├── SKILL.md                          # This file
├── lib/
│   ├── capture/                      # Error capture (from cfn-standardized-error-handling)
│   │   ├── capture-agent-error.sh    # Capture agent errors
│   │   └── README.md                 # Capture documentation
│   ├── batching/                     # Error batching (from cfn-error-batching-strategy)
│   │   ├── cli.sh                    # Batching CLI
│   │   ├── analyze-errors.sh         # Error analysis
│   │   ├── calculate-waves.sh        # Wave calculation
│   │   ├── cluster-files.sh          # File clustering
│   │   ├── create-batches.sh         # Batch creation
│   │   ├── templates/                # Batch templates
│   │   └── README.md                 # Batching documentation
│   └── logging/                      # Error logging (from cfn-error-logging)
│       ├── invoke-error-logging.sh   # Log errors
│       ├── cleanup-error-logs.sh     # Log cleanup
│       ├── src/                      # TypeScript implementation
│       └── README.md                 # Logging documentation
└── cli/                              # CLI wrappers
    ├── capture-error.sh              # → lib/capture/capture-agent-error.sh
    ├── batch-errors.sh               # → lib/batching/cli.sh
    └── log-error.sh                  # → lib/logging/invoke-error-logging.sh

---

Quick Start

1. Capture an Error

./cli/capture-error.sh \
  --agent-id "agent-123" \
  --error-type "TIMEOUT" \
  --message "Agent timed out after 900s" \
  --context "Loop 3 implementation"

2. Batch Errors for Processing

./cli/batch-errors.sh \
  --input errors.json \
  --max-batch-size 5 \
  --output batches.json

3. Log an Error

./cli/log-error.sh \
  --task-id "task-123" \
  --agent-id "agent-123" \
  --error-type "VALIDATION" \
  --message "Output validation failed"

---

Module Details

Capture Module (lib/capture/)

Purpose: Standardized error capture and categorization

Error Types:

• TIMEOUT - Agent execution timeout
• CRASH - Agent process crash
• VALIDATION - Output validation failure
• COORDINATION - Redis coordination failure
• UNKNOWN - Uncategorized errors

Features:

• Standardized error format
• Category-based recovery strategies
• Context preservation

Batching Module (lib/batching/)

Purpose: Group errors for batch agent processing

Features:

• Error clustering by file
• Wave calculation for parallel processing
• Tier-based batching (small/medium/large)
• Template-based batch configuration

Logging Module (lib/logging/)

Purpose: Error log storage and management

Features:

• Structured error logging
• Log cleanup and rotation
• Integration with CLI and Docker modes
• TypeScript implementation

---

Integration with CFN Loop

# 1. Capture error when agent fails
./cli/capture-error.sh \
  --agent-id "$AGENT_ID" \
  --error-type "TIMEOUT" \
  --message "$ERROR_MESSAGE"

# 2. Log the error
./cli/log-error.sh \
  --task-id "$TASK_ID" \
  --agent-id "$AGENT_ID" \
  --error-type "TIMEOUT"

# 3. Batch multiple errors for batch processing
./cli/batch-errors.sh --input collected-errors.json

---

Migration from Individual Skills

Old Paths → New Paths

Old Path	New Path
.claude/skills/cfn-standardized-error-handling/capture-agent-error.sh	.claude/skills/error-management/lib/capture/capture-agent-error.sh
.claude/skills/cfn-error-batching-strategy/cli.sh	.claude/skills/error-management/lib/batching/cli.sh
.claude/skills/cfn-error-logging/invoke-error-logging.sh	.claude/skills/error-management/lib/logging/invoke-error-logging.sh

---

Version History

1.0.0 (2025-12-02) - Mega-Skill Creation

• Merged: cfn-standardized-error-handling, cfn-error-batching-strategy, cfn-error-logging
• Added: CLI wrappers
• Added: Unified documentation

---

Dependencies

• Bash: 4.0+
• jq: JSON processing
• Node.js: TypeScript logging (optional)