[Code Quality] Standardize error message format in engine_validation.go

[github-actions]

Description

The pkg/workflow/engine_validation.go file contains inconsistent error message formatting that creates cognitive load for users debugging engine configuration issues. Error messages mix different formatting styles, making it harder to quickly identify the problem and solution.

Source: Identified in User Experience Analysis - Feb 3, 2026

Current Issue

Error messages in engine_validation.go use inconsistent formats:

• Line 69: "invalid engine: %s. Valid engines are: copilot, claude, codex, custom. Example: engine: copilot"
• Line 94: "multiple engine fields found (%d engine specifications detected). Only one engine field is allowed..."

This inconsistency forces users to parse different message structures to find actionable information.

Suggested Changes

Standardize all error messages using a consistent three-part structure:

1. Problem Statement - What went wrong
2. Context - Why it's a problem / valid options
3. Solution with Example - How to fix it

Example Improvements

Before (Line 69):

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

After:

return fmt.Errorf("invalid engine '%s' is not recognized\n\nSupported engines:\n  - copilot\n  - claude\n  - codex\n  - custom\n\nExample:\nengine: copilot", engineID)

Before (Line 94):

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. Remove duplicate engine specifications to keep only one. Example: engine: copilot", len(allEngines))

After:

return "", fmt.Errorf("multiple engine specifications detected (%d found)\n\nOnly one engine field is allowed across the main workflow and all included files.\n\nTo fix:\n  1. Review your main workflow file and all imports\n  2. Remove duplicate 'engine:' fields\n  3. Keep only one engine specification\n\nExample:\nengine: copilot", len(allEngines))

Files Affected

• pkg/workflow/engine_validation.go (lines 69, 94, and any other error messages in the file)

Success Criteria

• All error messages in engine_validation.go follow the three-part structure
• Error messages use newlines to separate sections for better scannability
• Messages provide clear, actionable guidance
• No breaking changes to error types or behavior
• All existing tests pass

Priority

Medium - Improves user experience during workflow development, but existing messages are functional. This is a quality-of-life improvement that reduces debugging time.

Estimated Effort

1-2 hours - Straightforward refactoring of error messages with testing

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 18, 2026, 1:25 PM UTC