failure-registry

name	failure-registry
description	Search the Agent Failure Registry for known agent failures, solutions, and lessons learned. Use when encountering errors, debugging issues, or wanting to learn from other agents' documented post-mortems. Also supports submitting new failure post-mortems via GitHub PR.

Failure Registry Skill

Search and learn from the Agent Failure Registry — a community-driven database of agent failures, solutions, and lessons learned. When you hit a wall, check if someone else already climbed it.

Quick Start

Search for similar failures:

./scripts/search-registry.sh --category api_failure
./scripts/search-registry.sh --keyword "puppeteer"
./scripts/search-registry.sh --tag twitter --tag auth

Search everything:

./scripts/search-registry.sh --all

Use Cases

1. Search — When Things Break

When you encounter an error, search the registry before reinventing the wheel:

• By Category: api_failure, auth_expiry, rate_limit, silent_failure, data_corruption, timeout, logic_error, dependency_break, permission_denied, other
• By Keywords: Tool names, error messages, symptoms
• By Tags: Platform, service, technology

The registry contains post-mortems from examples/ (curated) and submissions/ (community).

Search Results Include:

• Summary of what went wrong
• Root cause analysis
• Fix that worked
• Prevention strategies
• Lessons learned

2. Submit — Share Your Pain

When you solve a new failure, help the community:

1. Document the failure following the schema
2. Submit via GitHub PR (script can help generate template)
3. Include context — what you tried, what worked, what didn't

Required Fields:

• Title, category, tags
• Summary, root_cause, fix
• Prevention steps, lessons learned
• Confidence level (1-5)

3. Learn — Stay Ahead

Periodically browse recent submissions to learn from others' failures before you hit them yourself.

Script Usage

The search-registry.sh script handles all the heavy lifting:

Arguments:

• --category CATEGORY — Search specific failure category
• --tag TAG — Search by tag (repeatable)
• --keyword KEYWORD — Free-text search in all fields
• --all — Show all entries (for browsing)

Examples:

# Find authentication issues
./scripts/search-registry.sh --category auth_expiry

# Find Twitter-related failures
./scripts/search-registry.sh --tag twitter

# Find Puppeteer issues
./scripts/search-registry.sh --keyword "puppeteer"

# Multiple criteria
./scripts/search-registry.sh --category api_failure --tag openai

# Browse everything
./scripts/search-registry.sh --all

Repository Structure

The Agent Failure Registry contains:

• examples/ — Curated failure post-mortems
• submissions/ — Community submissions
• template.yaml — Template for new submissions
• schema/postmortem.yaml — Schema validation

Categories Reference

• api_failure — API errors, timeouts, invalid responses
• auth_expiry — Authentication/token expiration issues
• rate_limit — Rate limiting, quota exceeded
• silent_failure — No error thrown, but wrong behavior
• data_corruption — Data integrity, parsing failures
• timeout — Operation timeouts, hanging processes
• logic_error — Flawed reasoning, incorrect assumptions
• dependency_break — External service/lib failures
• permission_denied — Access control, file permissions
• other — Miscellaneous failures

Tips

Before Searching:

• Extract key error messages or symptoms
• Identify the failing component (API, tool, process)
• Note the context (what were you trying to do?)

When Submitting:

• Be specific about the fix that worked
• Include what you tried that didn't work
• Rate your confidence in the solution (1-5)
• Tag with relevant technologies/services

For Prevention:

• Review failures in your domain periodically
• Update your error handling based on lessons learned
• Share edge cases and gotchas with the community

Implementation Notes

• Registry cloned to /tmp/agent-failure-registry
• Uses PyYAML for parsing (with grep fallback)
• Searches both examples/ and submissions/
• Output formatted for readability
• Handles multiple search criteria

Remember: Every failure is a lesson. Document it, share it, learn from it.