[plan] Create error recovery patterns documentation

[github-actions]

Objective

Create comprehensive documentation for error handling patterns, common error scenarios, recovery strategies, and debugging techniques specific to gh-aw.

Context

Despite 51 references to error handling guides in the codebase, only 1 error message documentation exists. Developers need a comprehensive guide covering error patterns, recovery strategies, and debugging runbooks.

Files to Create/Modify

• Create: specs/error-recovery-patterns.md
• Update: AGENTS.md (add link to new doc in Available Skills Reference)

Documentation Structure

1. Error Handling Patterns

• Console formatting requirements with examples
• Error wrapping with %w best practices
• Debug logging standards
• Panic recovery (when/how to use)

2. Common Error Scenarios

• MCP configuration errors → recovery steps
• Permission validation errors → suggested fixes
• Network/firewall errors → debugging steps
• Workflow compilation errors → resolution guide

3. Error Message Templates

• Validation error template with example
• Runtime error template with context
• User-actionable error template
• System/internal error template

4. Debugging Runbook

• How to enable DEBUG logging
• Reading error chains with errors.As/errors.Is
• Analyzing validation failures
• Troubleshooting MCP server issues

5. Error Categorization

• User errors (fixable by user)
• Configuration errors (workflow changes needed)
• System errors (environment issues)
• Internal errors (code bugs - should be reported)

Acceptance Criteria

• New document created: specs/error-recovery-patterns.md
• Documents common error scenarios with solutions
• Includes error message templates and examples
• Provides debugging runbook for each error category
• Links to relevant validation files and handlers
• Indexed in AGENTS.md under Available Skills Reference
• Follows specs/ directory formatting conventions
• Includes code examples for each pattern

Reference Materials

Review existing docs for consistency:

• AGENTS.md - Console formatting guidelines
• specs/error-messages.md - Error message style guide
• specs/github-actions-security-best-practices.md - Security error handling
• pkg/console/ - Console formatting implementation
  Related to [plan] Improve Error Experience Engineering across gh-aw #9236

AI generated by Plan Command for discussion #9231