[Code Quality] Improve error message consistency in engine_validation.go

[github-actions]

Description

Error messages in pkg/workflow/engine_validation.go use inconsistent formatting styles, creating cognitive load for users who need to parse different message structures to find actionable information. Standardizing to a consistent three-part structure (Problem → Context → Solution) will improve user experience.

Current State

File: pkg/workflow/engine_validation.go

Inconsistent patterns:

• 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 across the main workflow and all included files. Remove duplicate engine specifications to keep only one. Example: engine: copilot"

Issues:

• Mixed formatting (inline text vs. structured guidance)
• Different verbosity levels (concise vs. verbose)
• Inconsistent example placement
• Not scannable (users must read full sentences)

Suggested Changes

Standardize all error messages in engine_validation.go using this three-part structure:

Pattern: Problem Statement → Context → Solution with Example

Change 1: Invalid Engine Error (Lines 69-70)

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' is not recognized\n\nSupported engines:\n  - copilot\n  - claude\n  - codex\n  - custom\n\nExample:\nengine: copilot", engineID)

Change 2: Multiple Engines Error (Lines 94-95)

Before:

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))

Why This Matters

• User Impact: Engineers encountering engine configuration errors get structured, scannable guidance instead of parsing long sentences
• Quality Factor: Enhances Professional Communication and Efficiency
• Frequency: Engine configuration is a fundamental workflow setup step encountered by all users
• Consistency: Aligns with error message best practices used elsewhere in the codebase

Files Affected

• MODIFY: pkg/workflow/engine_validation.go (lines 69-70, 94-95)

Success Criteria

• Both error messages follow three-part structure (Problem → Context → Solution)
• Error messages use newlines to separate sections
• Messages are easier to scan visually
• Examples are clearly separated from explanation text
• All tests in engine_validation_test.go still pass
• Error message tests updated if they validate exact error text

Source

Extracted from User Experience Analysis Report discussion #13593

Quote from report:

Opportunity 1: Enhance Error Message Consistency in Engine Validation - Single File Improvement

Design Principle: Clarity and Precision, Professional Communication

This inconsistency creates cognitive load for users who need to parse different message structures to find the actionable information.

Priority

HIGH - Error messages are a critical touchpoint for user experience, especially during initial workflow setup.

Scope Constraint

• Single file only: pkg/workflow/engine_validation.go
• No changes to other validation files required
• Can be completed independently

Estimated Effort

1-2 hours (update error messages, run tests, validate output)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 18, 2026, 1:30 AM UTC