[Code Quality] Add documentation links to common validation errors

[github-actions]

Description

Enhance validation error messages with documentation links for common error scenarios. Currently only 7 error messages include documentation references, and only 29% of validation errors include examples/suggestions.

Problem

Users lack guidance for common errors. No error code catalog or troubleshooting index exists. This increases support burden and slows down issue resolution.

Suggested Changes

Priority Validation Files

1. pkg/workflow/engine_validation.go - Engine configuration errors
2. pkg/workflow/mcp_config_validation.go - MCP server configuration errors
3. pkg/workflow/permissions_validation.go - GitHub permissions errors
4. pkg/workflow/github_tool_validation.go - GitHub tools configuration errors
5. pkg/workflow/safe_inputs_validation.go - Safe inputs configuration errors

Implementation Pattern

// ❌ BEFORE - Error without documentation
return fmt.Errorf("invalid engine: %s. Valid engines are: copilot, claude, codex, custom", engineID)

// ✅ AFTER - Error with documentation and example
return fmt.Errorf("invalid engine: %s. Valid engines are: copilot, claude, codex, custom.\n\nExample:\nengine: copilot\n\nSee: https://github.com/github/gh-aw/blob/main/docs/reference/workflow-frontmatter.md#engine", engineID)

Example Enhanced Error

return fmt.Errorf("MCP server '%s' missing required 'command' field.\n\nExample:\nmcp-servers:\n  %s:\n    command: npx\n    args:\n      - -y\n      - `@modelcontextprotocol/server-github`\n\nSee: https://github.com/github/gh-aw/blob/main/docs/reference/mcp-servers.md#configuration", serverName, serverName)

Success Criteria

• Identify top 20 most common validation errors from code analysis
• Add documentation links to each error message (format: See: https://github.com/github/gh-aw/blob/main/docs/...)
• Ensure documentation pages exist or create missing pages
• Update validation error messages to include actionable examples
• Test error messages display correctly in terminal

Documentation Pages to Reference

• docs/reference/workflow-frontmatter.md - Workflow configuration
• docs/reference/mcp-servers.md - MCP server setup
• docs/reference/permissions.md - GitHub permissions
• docs/guides/troubleshooting.md - Common issues

Impact

Users get instant access to documentation when errors occur, enabling self-service support.

Source

Extracted from Error Experience Engineering Discussion #12265

Priority

Medium - Improves self-service support

Estimated Effort

Medium (1 week)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 18, 2026, 9:08 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster