[WIP] Create validation error message style guide

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Create validation error message style guide</issue_title>
<issue_description>### Description

Create a comprehensive style guide at skills/validation-error-messages.md documenting best practices for writing clear, actionable validation error messages. This guide will establish a foundation for improving validation message quality across 87 validation files totaling 22,311 lines of code.

Current Situation

• 87 validation files with 22,311 LOC
• 127 fmt.Errorf error sites creating user-facing errors
• Only 29% of errors include examples
• Only 10% reference documentation
• 0 validation errors use console formatting
• Error message quality varies dramatically between validators

Style Guide Requirements

The guide should include:

1. Message Anatomy: Define what makes an excellent validation error

   • Problem statement (what's wrong)
   • Context (which field, which value)
   • Valid options (what's allowed)
   • Concrete example (how to fix it)
   • Documentation reference (optional, for complex cases)

2. Templates for Common Scenarios:

   • Missing required field
   • Invalid field type
   • Invalid field value (with valid options)
   • Configuration conflict (multiple fields)
   • Permission/capability not available
   • Deprecated field usage
   • Complex validation failure (multiple issues)

3. Before/After Examples from actual codebase:

   • ✅ Good: engine_validation.go line 28
   • ✅ Good: mcp_config_validation.go line 47
   • ✅ Gold standard: github_toolset_validation_error.go (entire file)
   • ⚠️ Needs improvement: Identify 3 examples that could be enhanced

4. Testing Requirements:

   • Every validation error message MUST have test checking content
   • Use assert.Contains() to verify examples present
   • Use assert.Contains() to verify valid options listed
   • Target: 80%+ of error tests validate specific content

5. Specialized Error Types:

   • When to create custom error type (like GitHubToolsetValidationError)
   • When simple fmt.Errorf is sufficient
   • How to implement Error() method with structured output

6. Console Formatting Integration:

   • How validation errors should integrate with console formatting
   • Where formatting happens (validation layer vs CLI layer)
   • Current gap: 0 console.FormatErrorMessage calls in validation

Gold Standard Examples

engine_validation.go demonstrates excellent error messages:

return fmt.Errorf("invalid engine: %s. Valid engines are: copilot, claude, codex, custom. Example: engine: copilot", engineID)

✅ Lists valid options, provides concrete example, clear error description

GitHubToolsetValidationError sets the bar:

• Structured error type with detailed context
• Sorted output for consistency
• Actionable fix suggestion with complete YAML example
• Clear explanation of why error occurred

Success Criteria

• New file skills/validation-error-messages.md created
• Includes 5+ before/after examples from actual codebase
• Provides reusable templates for 7+ common error scenarios
• Documents testing requirements for validation errors
• References GitHubToolsetValidationError as the gold standard
• Includes decision tree for when to create specialized error types
• File follows existing skills/ directory format

Expected Outcomes

• Developers creating new validators have clear guidance on message quality
• Consistent error message structure across all 87 validation files
• Foundation for improving existing validation messages
• Testable standards for error message quality

Priority

High - Establishes foundation for all validation message improvements

Estimated Effort

Medium (1-2 days)

Source

Extracted from Repository Quality Improvement Report githubnext/gh-aw#11292 - Validation Message Clarity & Developer Guidance (Task 1)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 12, 2026, 9:09 PM UTC

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

• Fixes [Code Quality] Create validation error message style guide #12618

---

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