Create error recovery patterns documentation

[Copilot]

Despite 51 references to error handling guides in the codebase, only one error message documentation existed. This created a gap in developer guidance for error patterns, recovery strategies, and debugging techniques.

Changes

New Documentation: specs/error-recovery-patterns.md (1,137 lines)

• Error Handling Patterns - Console formatting requirements, error wrapping (%w vs breaking chains), debug logging with DEBUG env var, panic recovery guidelines
• Common Error Scenarios - 13 scenarios with step-by-step recovery:
  • MCP configuration (missing fields, type inference, HTTP/stdio conflicts)
  • Permissions (strict mode, GitHub toolset requirements)
  • Network (wildcard restrictions, firewall configuration)
  • Compilation (YAML syntax, YAML 1.1 vs 1.2, expression limits)
• Error Message Templates - Structured patterns for validation, runtime, user-actionable, and internal errors
• Debugging Runbook - DEBUG pattern matching, error chain analysis, validation failure procedures, MCP troubleshooting
• Error Categorization - Decision tree and handling approaches for user/config/system/internal errors

Updated: AGENTS.md - Indexed new documentation in Core Development Skills

Example

Console formatting requirement:

// ✅ CORRECT
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))

// ❌ INCORRECT - exposes internal types
return fmt.Errorf("failed to parse: %w", yamlErr)

MCP configuration recovery:

# Error: missing required field 'url' for http type
tools:
  my-server:
    type: http
    url: "https://api.example.com"  # Add this

Links to 11 validation files, 6 related docs. Includes mermaid decision trees and reference tables for quick lookup.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login ithub/workflows go /usr/bin/git -json GO111MODULE 64/bin/go git rev-�� ithub/workflows go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -json GO111MODULE 64/bin/go /opt/hostedtoolc1012 (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login /ref/tags/v8 go (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login pload-artifact/g--workflow go eb87b34cb2e48008f0d6b276dc61471981f/log.json -json 816f67fd0234192brun 64/bin/go /usr/lib/git-cor12345 http�� k/gh-aw/gh-aw/.g/tmp/gh-aw-test-runs/20260107-150926-31320/test-orchestrator-3679073369/run-1234/usr/bin/networkctl go /usr/bin/git 4976089/run-2 GO111MODULE 64/bin/go git (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Create error recovery patterns documentation</issue_title>
<issue_description>## 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

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Create error recovery patterns documentation #9240

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.