Enhance dispatch-workflow validation errors with actionable guidance

[Copilot]

Validation errors in dispatch-workflow configuration provided minimal context, forcing users to search documentation or source code to understand resolution steps.

Changes

Enhanced 4 validation error messages (pkg/workflow/dispatch_workflow_validation.go):

• Empty workflows list: Added YAML configuration example
• Workflow not found: Added file extension search details and resolution steps
• Self-reference: Added explanation of infinite loop prevention and alternatives
• Uncompiled workflow: Added exact compilation commands and common pitfalls

Added comprehensive test coverage (pkg/workflow/dispatch_workflow_validation_test.go):

• 5 new test functions validating error message content
• Tests verify presence of problem statement, context, resolution steps, and examples

Fixed linter compliance (.golangci.yml):

• Added staticcheck ST1005 exclusion for multi-line error messages
• Formatted error strings to avoid trailing punctuation

Example

Before:

dispatch-workflow: workflow 'ci' not found in /repo/.github/workflows (tried .md, .lock.yml, and .yml extensions)

After:

dispatch-workflow: workflow 'ci' not found in /repo/.github/workflows

Checked for: ci.md, ci.lock.yml, ci.yml

To fix:
1. Verify the workflow file exists in .github/workflows/
2. Ensure the filename matches exactly (case-sensitive)
3. Use the filename without extension in your configuration

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Enhance dispatch-workflow validation error messages with actionable guidance</issue_title>
<issue_description>## 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 github/gh-aw#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

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Enhance dispatch-workflow validation error messages with actionable guidance #14439

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Improves the developer/user experience of dispatch-workflow configuration validation by making key errors more actionable, and adds unit tests to lock in the improved messaging.

Changes:

• Expanded several dispatch-workflow validation errors with troubleshooting steps and examples.
• Added new unit tests validating the presence of actionable guidance in these error messages.
• Updated golangci-lint configuration to exclude staticcheck ST1005 for specific files.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
pkg/workflow/dispatch_workflow_validation.go	Enhances multiple validation error messages with multi-line guidance.
pkg/workflow/dispatch_workflow_validation_test.go	Adds tests asserting the improved error message content and aggregation behavior.
.golangci.yml	Adjusts staticcheck ST1005 exclusion rules for relevant files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This staticcheck exclusion matches the full ST1005 message text. Staticcheck’s wording has changed across versions (e.g., including “should not be capitalized…” and “a newline”), so this exact match is brittle and may stop excluding ST1005 unexpectedly. Prefer matching on the code only (e.g., "ST1005:" or "^ST1005:") or using a broader regex so the exclusion remains stable across toolchain updates.

Suggested change

	text: "ST1005: error strings should not end with punctuation or newlines" # Allow multiline user-facing error messages with formatting
	path: pkg/workflow/compiler_orchestrator\.go
	- linters:
	- staticcheck
	text: "ST1005: error strings should not end with punctuation or newlines" # Allow multiline user-facing error messages with formatting
	text: "^ST1005:" # Allow multiline user-facing error messages with formatting
	path: pkg/workflow/compiler_orchestrator\.go
	- linters:
	- staticcheck
	text: "^ST1005:" # Allow multiline user-facing error messages with formatting

[Copilot]

The empty-workflows error guidance says names should match the filename without the ".md" extension, but dispatch-workflow validation also accepts ".yml" and compiled ".lock.yml" targets. To avoid misleading users, update this line to say "filename without extension" (or mention both .md and .yml explicitly).

Suggested change

	return fmt.Errorf("dispatch-workflow: must specify at least one workflow in the list\n\nExample configuration in workflow frontmatter:\nsafe-outputs:\n dispatch-workflow:\n workflows: [workflow-name-1, workflow-name-2]\n\nWorkflow names should match the filename without the .md extension")
	return fmt.Errorf("dispatch-workflow: must specify at least one workflow in the list\n\nExample configuration in workflow frontmatter:\nsafe-outputs:\n dispatch-workflow:\n workflows: [workflow-name-1, workflow-name-2]\n\nWorkflow names should match the filename without the extension (for example, 'my-workflow' for 'my-workflow.md' or 'my-workflow.yml').")