[plan] Enhance error messages with recovery suggestions and actionable guidance

[github-actions]

Objective

Augment error messages throughout the CLI with actionable recovery suggestions, transforming cryptic failures into helpful guidance that enables users to self-recover.

Context

Currently, error messages lack recovery suggestions, forcing users to seek support or guess solutions. This creates friction and increases support burden.

Scope

Enhance error messages with:

• Root cause explanation: Why did this fail?
• Suggested fix command: Exact command to run to fix the issue
• Documentation link: Relevant docs section for this error type
• Common causes: "This often happens when..."
• Next steps: What should the user do?

Approach

1. Error Enhancement System (pkg/errors/recovery.go):

   • Create ErrorWithRecovery struct with structured recovery guidance
   • Implement EnhanceError(err error, errorType string) function
   • Create error type mappings for common errors:
     • frontmatter_syntax_error → Suggest frontmatter validator
     • missing_required_field → Show field name and example
     • invalid_action_version → Suggest gh aw update
     • stale_lock_file → Suggest gh aw sync
     • mcp_server_unreachable → MCP troubleshooting steps
     • github_api_auth_error → Authentication setup guide
   • Format enhanced errors using console formatting

2. Integration Strategy:

   • Replace generic error messages with enhanced errors in:
     • pkg/cli/compile_command.go (compilation failures)
     • pkg/cli/update_command.go (update failures)
     • pkg/cli/mcp_*.go (MCP server errors)
     • pkg/cli/trial_command.go (API errors)
     • pkg/workflow/compiler.go (compilation errors)
   • Show exact location for syntax/validation errors
   • Provide command suggestions for automatable fixes
   • Link to relevant documentation

3. Error Message Format:

   ❌ Compilation failed: Invalid frontmatter syntax
   
   Root Cause: Missing closing '---' delimiter in frontmatter
   Location: Line 15 in ci-doctor.md
   
   Suggested Fix:
     Add '---' at the end of your frontmatter section
   
   Common Causes:
     - Forgot closing delimiter
     - Extra spaces before/after delimiter
   
   Next Steps:
     1. Open ci-doctor.md and add '---' at line 15
     2. Run: gh aw compile ci-doctor.md --validate
     3. See docs: https://github.com/githubnext/gh-aw#frontmatter
   

Files to Modify

• Create: pkg/errors/recovery.go (error enhancement system)
• Create: pkg/errors/recovery_test.go (tests)
• Update: pkg/cli/compile_command.go (enhance compilation errors)
• Update: pkg/cli/update_command.go (enhance update errors)
• Update: pkg/cli/mcp_*.go (enhance MCP errors)
• Update: pkg/cli/trial_command.go (enhance API errors)
• Update: pkg/workflow/compiler.go (enhance compiler errors)
• Create: docs/troubleshooting.md (comprehensive troubleshooting guide)
• Update: Documentation (error code reference)

Acceptance Criteria

• Create error message enhancement system for structured recovery guidance
• Enhance compilation errors with specific fix suggestions
• Enhance validation errors with field-level guidance
• Enhance MCP errors with server troubleshooting steps
• Enhance API errors with authentication/permission guidance
• Each error includes: root cause, suggested fix, docs link, next steps
• Implement error message mapping for common error types
• Tests verify enhanced error messages contain required components
• Updates documentation with error troubleshooting guide

Example Enhanced Errors

# Stale lock file error
❌ Lock file out of sync
Root Cause: ci-doctor.md modified after ci-doctor.lock.yml compilation
Suggested Fix: gh aw sync ci-doctor
Next Steps: Run 'gh aw check' to find all stale workflows
Docs: https://github.com/githubnext/gh-aw#lock-files

# Invalid action error
❌ Invalid action version
Root Cause: actions/checkout@v2 is outdated (current: v4)
Suggested Fix: gh aw update ci-doctor --preview
Common Causes: Workflow not updated in 2+ years
Next Steps: Review breaking changes before updating
Docs: https://github.com/githubnext/gh-aw#action-updates

References

• Existing error messages: pkg/cli/ commands
• Console formatting: pkg/console/console.go
• Error handling patterns throughout codebase
• Documentation: docs/ directory
  Related to [plan] Implement CLI Resilience and Self-Healing Operations #5860

AI generated by Plan Command for discussion #5852