[plan] Add error prioritization and recovery suggestions to compilation flow #33320

Objective

Enhance the compilation error reporting to prioritize critical errors and suggest recovery strategies, reducing user overwhelm from long error lists.

Context

From discussion #33307: When compilation fails with multiple errors, users see a long list without guidance on which errors to fix first or how to recover. This task adds intelligent error prioritization and recovery suggestions to improve success rate on first compilation attempt.

Approach

1. Error Categorization: Classify errors by severity (critical, high, medium, low)
2. Prioritized Reporting: Show critical errors first, group related errors
3. Recovery Suggestions: Provide multi-step recovery plans for common error patterns
4. Progressive Disclosure: Show top 5 errors initially, allow "show all" option
5. Error Correlation: Detect cascading errors (one root cause → many symptoms)

Error Severity Levels

Critical (Fix these first):

• Invalid YAML syntax (prevents any parsing)
• Missing required fields (engine, workflow ID)
• Invalid engine name (workflow can't run)

High (Core functionality broken):

• Network permission violations in strict mode
• MCP server configuration errors
• Tool configuration errors

Medium (Workflow may run but will likely fail):

• Event filter configuration issues
• Permission scope issues
• Runtime version conflicts

Low (Warnings, best practices):

• Deprecated field usage
• Performance optimization suggestions
• Style/formatting issues

Example Implementation

Error Prioritization:

// pkg/workflow/error_collector.go
type ErrorSeverity int

const (
    SeverityCritical ErrorSeverity = iota
    SeverityHigh
    SeverityMedium
    SeverityLow
)

type PrioritizedError struct {
    Error    *WorkflowValidationError
    Severity ErrorSeverity
    Category string // "syntax", "configuration", "permissions", etc.
}

func (ec *ErrorCollector) GetPrioritizedErrors() []PrioritizedError {
    // Sort by severity, group by category
    // Detect cascading errors (suppress duplicates)
}

Recovery Suggestions:

// pkg/workflow/error_recovery.go
type RecoveryPlan struct {
    ErrorPattern string
    Steps        []string
    Examples     []string
}

func SuggestRecovery(errors []PrioritizedError) *RecoveryPlan {
    // Common patterns:
    // - "Invalid YAML syntax" → "Run workflow through YAML validator"
    // - "Missing engine" → "Add 'engine: copilot' to frontmatter"
    // - "Network permission denied" → "Remove network.allowed or disable strict mode"
}

Files to Modify

• Update: pkg/workflow/error_collector.go (add severity levels and prioritization)
• Create: pkg/workflow/error_recovery.go (recovery suggestion engine)
• Create: pkg/workflow/error_recovery_test.go (test recovery suggestions)
• Update: pkg/workflow/compiler.go (use prioritized error reporting)
• Update: pkg/cli/compile_command.go (display prioritized errors with recovery plans)
• Update: pkg/workflow/errors.go (add Severity field to WorkflowValidationError)

User Experience Flow

Before:

Error: failed to compile workflow
  - invalid engine: copiliot
  - network.allowed requires strict_mode: true
  - missing tools.github.version
  - invalid event type: pull-request
  - cache key cannot use github.run_id
  ... 15 more errors

After:

⚠️  Compilation failed with 20 errors (showing top 5 critical issues)

🔴 CRITICAL (fix first):
  1. Invalid engine name 'copiliot'
     → Did you mean 'copilot'? Valid engines: copilot, claude, codex, custom
  
  2. Invalid YAML syntax at line 15
     → Run 'gh aw validate workflow.md' for detailed syntax errors

🟠 HIGH PRIORITY:
  3. Network permissions require strict mode
     → Add 'strict_mode: true' to frontmatter or remove 'network.allowed'
  
  4. Invalid event type 'pull-request'
     → Did you mean 'pull_request'? (underscore, not hyphen)

💡 RECOVERY PLAN:
  Step 1: Fix critical syntax and configuration errors (issues 1-2)
  Step 2: Recompile to see if other errors are cascading from these
  Step 3: Address remaining high-priority issues (issues 3-4)

Run 'gh aw compile --show-all' to see all 20 errors

Acceptance Criteria

• Errors are categorized by severity (critical, high, medium, low)
• Error reporting shows top 5 critical errors by default
• --show-all flag displays complete error list
• Recovery suggestions provided for common error patterns
• Cascading errors are detected and suppressed (e.g., invalid YAML → many parse errors)
• Error groups are visually distinct (colors, icons, or formatting)
• Multi-error scenarios include step-by-step recovery plan
• Run make agent-finish successfully before committing

Testing Strategy

1. Create workflow with multiple intentional errors at different severity levels
2. Verify errors are displayed in priority order
3. Test that --show-all flag shows complete list
4. Verify recovery suggestions match error patterns
5. Test cascading error detection (one root cause suppresses symptoms)
6. Ensure single-error case still works correctly

Edge Cases

• Workflow with only low-severity warnings (no errors)
• Workflow with 100+ errors (performance of prioritization)
• Errors without clear severity classification (default to medium)
• Recovery suggestions for unknown error patterns (generic guidance)

Reference

• Source: Discussion [repository-quality] Repository Quality Improvement Report - Error Message UX & Actionability #33307 (Repository Quality Improvement Report - Error Message UX)
• Pattern: Compiler error reporting in modern languages (Rust, TypeScript)
• Similar feature: eslint error prioritization and fix suggestions
• Console formatting: Use pkg/console for colored output

Generated by 📋 Plan Command · ● 12.7M · ◷

• expires on May 21, 2026, 2:12 PM UTC