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.