Add documentation links to validation error messages with centralized URL constants

[Copilot]

Validation errors lacked documentation references, forcing users to manually search for help. Enhanced 23 error messages across 6 validation files to include direct documentation links and actionable examples. All documentation URLs are now centralized in typed constants for easier maintenance.

Changes

Documentation URL Management

• Added DocURL semantic type to pkg/constants/constants.go following existing patterns (URL, Version, ModelName, etc.)
• Defined 5 documentation URL constants in a single location:
  • DocsEnginesURL - engine configuration documentation
  • DocsToolsURL - tools/MCP server documentation
  • DocsGitHubToolsURL - GitHub tools documentation
  • DocsPermissionsURL - permissions documentation
  • DocsSandboxURL - sandbox configuration documentation

Enhanced validation files

• engine_validation.go (4 errors) → constants.DocsEnginesURL
• mcp_config_validation.go (11 errors) → constants.DocsToolsURL
• permissions_validation.go (1 error) → constants.DocsPermissionsURL
• github_toolset_validation_error.go (1 error) → constants.DocsGitHubToolsURL
• docker_validation.go (2 errors) → constants.DocsToolsURL
• sandbox_validation.go (5 errors) → constants.DocsSandboxURL

Error format

// Before
return fmt.Errorf("tool '%s' must specify either 'command' or 'container'", toolName)

// After
return fmt.Errorf(`tool '%s' must specify either 'command' or 'container'.

Example (command):
tools:
  %s:
    command: "node server.js"
    args: ["--port", "3000"]

Example (container):
tools:
  %s:
    container: "my-registry/my-tool"
    version: "latest"

See: %s`, toolName, toolName, toolName, constants.DocsToolsURL)

Benefits

• Single Source of Truth: All documentation URLs maintained in one location
• Type Safety: DocURL type prevents mixing with arbitrary strings
• Easy Maintenance: Update URLs in one place when docs structure changes
• Consistent Pattern: Follows existing semantic type pattern in constants package

Test updates

• Updated error_message_quality_test.go to use tools: (current syntax) vs mcp-servers: (deprecated)
• Fixed test expectations for enhanced error format patterns

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add documentation links to common validation errors</issue_title>
<issue_description>## 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 github/gh-aw#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

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

• Fixes [Code Quality] Add documentation links to common validation errors #13789

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot keep the list of all documentation url in constants using a typed string to maintain the list in a single location

[pelikhan]

@copilot keep working

[Copilot]

@copilot keep working

Completed refactoring documentation URLs to use typed constants (commit e6c0257).

All 24 documentation URLs across 6 validation files now use centralized DocURL constants from pkg/constants/constants.go:

• DocsEnginesURL - engine configuration docs
• DocsToolsURL - tools/MCP server docs
• DocsGitHubToolsURL - GitHub tools docs
• DocsPermissionsURL - permissions docs
• DocsSandboxURL - sandbox configuration docs

This follows the existing semantic type pattern used in the constants package (URL, Version, ModelName, etc.) and provides a single location for maintaining all documentation links.

[Copilot]

Pull request overview

This PR enhances validation error messages across 6 validation files by adding direct documentation links and actionable examples. A new DocURL semantic type was introduced in the constants package to centralize all documentation URLs, following the existing pattern of semantic types (Version, ModelName, etc.). The changes affect 24 error messages in total, providing users with immediate access to documentation when errors occur.

Changes:

• Added DocURL semantic type with 5 documentation URL constants in pkg/constants/constants.go
• Enhanced 24 error messages across 6 validation files with documentation links and improved examples
• Updated tests to reflect current tools: syntax (replacing deprecated mcp-servers: references)

Reviewed changes

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

Show a summary per file

File	Description
pkg/constants/constants.go	Introduces DocURL semantic type and 5 centralized documentation URL constants following existing patterns
pkg/workflow/engine_validation.go	Adds documentation links to 4 engine configuration error messages
pkg/workflow/mcp_config_validation.go	Enhances 11 MCP server configuration errors with examples and documentation links
pkg/workflow/permissions_validation.go	Adds documentation link to permissions error message
pkg/workflow/github_toolset_validation_error.go	Adds documentation link to GitHub toolset validation error
pkg/workflow/docker_validation.go	Enhances 2 Docker image validation errors with examples and documentation links
pkg/workflow/sandbox_validation.go	Adds documentation links to 5 sandbox configuration validation errors
pkg/workflow/error_message_quality_test.go	Updates test expectations to match new error format with current tools: syntax

Comments suppressed due to low confidence (2)

pkg/workflow/error_message_quality_test.go:127

• Changing from "Example:" to "Example" makes this test assertion less specific. The colon is important as it indicates the start of an example block. Without it, the test would pass even if the word "Example" appeared elsewhere in the error message (e.g., "For example, you could..."). Consider keeping the colon to ensure the test verifies the proper example formatting pattern.

				"Example",

pkg/workflow/error_message_quality_test.go:295

• Changing from "Example:" to "Example" makes this test assertion less specific. The colon is important as it indicates the start of an example block. Without it, the test would pass even if the word "Example" appeared elsewhere in the error message (e.g., "For example, you could..."). Consider keeping the colon to ensure the test verifies the proper example formatting pattern.

				"Example",

---

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

[Copilot]

Changing from "Example:" to "Example" makes this test assertion less specific. The colon is important as it indicates the start of an example block. Without it, the test would pass even if the word "Example" appeared elsewhere in the error message (e.g., "For example, you could..."). Consider keeping the colon to ensure the test verifies the proper example formatting pattern.

This issue also appears in the following locations of the same file:

• line 127
• line 295

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: medium | Priority: 22/100

Scores Breakdown

• Impact: 10/50 - Documentation improvements to validation error messages
• Urgency: 0/30 - Recent PR (1.4 hours old)
• Quality: 12/20 - Ready for review (not draft), CI pending, fixes issue [Code Quality] Add documentation links to common validation errors #13789

📋 Recommended Action: batch_review

Enhances validation error messages with documentation links. This is a quality-of-life improvement that benefits users. The PR is ready for review (not in draft state) with clean mergeable state.

---

Triaged by PR Triage Agent on 2026-02-05

AI generated by PR Triage Agent

[github-actions]

🎬 THE END — Smoke Claude MISSION: ACCOMPLISHED! The hero saves the day! ✨

[github-actions]

🎉 Yo ho ho! Changeset Generator found the treasure and completed successfully! ⚓💰

Unable to create a changeset because the sanitized pull request content and diff are unavailable in this environment; no factual summary can be produced.

[github-actions]

🌑 The shadows whisper... Smoke Codex failed. The oracle requires further meditation...

[github-actions]

📰 BREAKING: Smoke Copilot is now investigating this pull request. Sources say the story is developing...

[github-actions]

Agent Container Tool Smoke Test Results

Tool	Status	Version
bash	✅	5.2.21
sh	✅	available
git	✅	2.52.0
jq	✅	1.7
yq	✅	4.50.1
curl	✅	8.5.0
gh	✅	2.86.0
node	✅	20.20.0
python3	✅	3.12.3
go	✅	1.24.12
java	❌	Error: libjli.so missing
dotnet	❌	Error: cannot execute when renamed to bash

Result: 10/12 tools available ❌ FAIL

Issues Found

1. Java: Missing shared library libjli.so - Java runtime appears installed but not properly configured
2. .NET: Binary execution error - dotnet command fails with "cannot execute when renamed to bash" error

Both runtimes are present in the filesystem but cannot execute successfully.

AI generated by Agent Container Smoke Test

[github-actions]

Smoke Test Results for PR #13809

PRs tested: #13820, #13809

✅ GitHub MCP
✅ Safe Inputs GH CLI
✅ Serena MCP
✅ Playwright
✅ File Writing
✅ Bash Tool
✅ Discussion Comment
✅ Build gh-aw
✅ Workflow Dispatch

Status: PASS

@pelikhan @Copilot

AI generated by Smoke Copilot

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤