[Code Quality] Enhance error messages in engine_validation.go with concrete YAML examples

[github-actions]

Description

Error messages in engine_validation.go provide valid options but lack concrete usage examples, forcing users to navigate away to find correct configuration patterns. The User Experience Analysis identified this as a clarity and precision issue.

Current State

• File: pkg/workflow/engine_validation.go
• Lines: 69, 94, 105, 120
• Issue: Generic format hints without concrete examples
• Impact: Users receive validation errors without seeing exactly how to fix them

Suggested Changes

Add properly formatted YAML examples to each error message:

Line 69 - Invalid engine error:

// BEFORE
return fmt.Errorf("invalid engine: %s. Valid engines are: copilot, claude, codex, custom. Example: engine: copilot", engineID)

// AFTER
return fmt.Errorf("invalid engine: %s. Valid engines are: copilot, claude, codex, custom.\\n\\nExample configuration:\\n---\\nengine: copilot\\n---\\n\\nFor custom engines, see: (githubnext.github.io/redacted), engineID)

Line 94 - Multiple engine fields:

// AFTER (improved)
return "", fmt.Errorf("multiple engine fields found (%d engine specifications detected). Only one engine field is allowed across the main workflow and all included files.\\n\\nTo fix: Remove duplicate engine specifications from either:\\n  • Your main workflow frontmatter\\n  • Imported workflow files\\n\\nKeep only one engine field:\\n---\\nengine: copilot\\n---", len(allEngines))

Line 105 - Parse error:

// AFTER (improved)
return "", fmt.Errorf("failed to parse included engine configuration: %w.\\n\\nExpected formats:\\n\\nString format:\\n---\\nengine: copilot\\n---\\n\\nObject format:\\n---\\nengine:\\n  id: copilot\\n  model: gpt-4\\n---", err)

Line 120 - Missing ID field:

// AFTER (improved)
return "", fmt.Errorf("invalid engine configuration in included file, missing or invalid 'id' field.\\n\\nExpected formats:\\n\\nString format:\\n---\\nengine: copilot\\n---\\n\\nObject format:\\n---\\nengine:\\n  id: copilot\\n  model: gpt-4\\n---")

Files Affected

• pkg/workflow/engine_validation.go (lines 69, 94, 105, 120)

Success Criteria

• All 4 error messages include properly formatted YAML examples
• Error messages use \\n for line breaks (not \\\\n)
• Examples show both string and object formats where applicable
• Professional tone maintained
• All existing tests pass
• Manual testing confirms examples are copy-pasteable

Benefits

• Faster resolution: Users can copy-paste correct configuration directly from error messages
• Reduced support burden: Clear examples reduce need for documentation lookups
• Better UX: Resolves configuration errors in seconds instead of minutes
• Professional polish: Demonstrates attention to developer experience

Source

Extracted from User Experience Analysis discussion #12700

Priority

Medium - Improves developer experience during initial setup and configuration

Estimated Effort

1-2 hours

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 9:14 AM UTC