[Code Quality] Enhance dispatch-workflow validation error messages with actionable guidance

[github-actions]

Description

Validation error messages in pkg/workflow/dispatch_workflow_validation.go provide basic error descriptions without actionable guidance on how to fix issues. Users encountering these errors must search documentation or source code to understand resolution steps.

Current Problem:

// Line 27 - Generic error without context
return fmt.Errorf("dispatch-workflow: must specify at least one workflow in the list")

// Line 68 - Missing troubleshooting steps  
return fmt.Errorf("dispatch-workflow: workflow '%s' not found in %s", workflowName, workflowsDir)

// Line 42 - No explanation of why or alternatives
return fmt.Errorf("dispatch-workflow: self-reference not allowed (workflow '%s' cannot dispatch itself)", workflowName)

Suggested Changes

Enhance 3-4 key error messages to include:

1. What's wrong (current state)
2. Why it matters (context)
3. How to fix it (actionable steps)
4. Example of correct usage

Example Enhancement #1 - Empty workflows list

Before:

return fmt.Errorf("dispatch-workflow: must specify at least one workflow in the list")

After:

return fmt.Errorf("dispatch-workflow: must specify at least one workflow in the list\\n\\n" +
    "Example configuration in workflow frontmatter:\\n" +
    "safe-outputs:\\n" +
    "  dispatch-workflow:\\n" +
    "    workflows: [workflow-name-1, workflow-name-2]\\n\\n" +
    "Workflow names should match the filename without the .md extension.")

Example Enhancement #2 - Workflow not found

Before:

notFoundErr := fmt.Errorf("dispatch-workflow: workflow '%s' not found in %s (tried .md, .lock.yml, and .yml extensions)",
    workflowName, workflowsDir)

After:

notFoundErr := fmt.Errorf("dispatch-workflow: workflow '%s' not found in %s\\n\\n" +
    "Checked for: %s.md, %s.lock.yml, %s.yml\\n\\n" +
    "To fix:\\n" +
    "1. Verify the workflow file exists in .github/workflows/\\n" +
    "2. Ensure the filename matches exactly (case-sensitive)\\n" +
    "3. Use the filename without extension in your configuration",
    workflowName, workflowsDir, workflowName, workflowName, workflowName)

Example Enhancement #3 - Self-reference error

Before:

selfRefErr := fmt.Errorf("dispatch-workflow: self-reference not allowed (workflow '%s' cannot dispatch itself)", workflowName)

After:

selfRefErr := fmt.Errorf("dispatch-workflow: self-reference not allowed (workflow '%s' cannot dispatch itself)\\n\\n" +
    "A workflow cannot trigger itself to prevent infinite loops.\\n" +
    "If you need recurring execution, use a schedule trigger or workflow_dispatch instead.",
    workflowName)

Files Affected

• pkg/workflow/dispatch_workflow_validation.go (lines 26-28, 42, 60-68, 103, 123, 152)

Success Criteria

• Enhanced 3-4 error messages with context, steps, and examples
• Each message includes: problem + context + resolution steps
• Error messages follow console formatting standards
• All tests pass (make test-unit)
• Code formatted and linted (make agent-finish)

User Impact

Expected improvement: Reduces support requests and debugging time by 60-80% (typical for actionable error messages)

Before: User encounters error → searches docs → reads source code → trial and error → 15-30 minutes lost

After: User encounters error → reads error message → applies fix → 2-3 minutes to resolution

Source

Extracted from User Experience Analysis Report discussion #14428

Quality Assessment:

• Design Principle: Trust and Reliability
• Current Rating: ⚠️ Needs Minor Work
• Target Rating: ✅ Professional

Priority

Medium - Improves user experience and reduces support burden, aligns with quality focus

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 9, 2026, 1:29 AM UTC