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:
-
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)
-
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)
-
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
-
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
-
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
-
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
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 #11292 - Validation Message Clarity & Developer Guidance (Task 1)
AI generated by Discussion Task Miner - Code Quality Improvement Agent
Description
Create a comprehensive style guide at
skills/validation-error-messages.mddocumenting 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
Style Guide Requirements
The guide should include:
Message Anatomy: Define what makes an excellent validation error
Templates for Common Scenarios:
Before/After Examples from actual codebase:
engine_validation.goline 28mcp_config_validation.goline 47github_toolset_validation_error.go(entire file)Testing Requirements:
assert.Contains()to verify examples presentassert.Contains()to verify valid options listedSpecialized Error Types:
GitHubToolsetValidationError)fmt.Errorfis sufficientError()method with structured outputConsole Formatting Integration:
console.FormatErrorMessagecalls in validationGold Standard Examples
engine_validation.go demonstrates excellent error messages:
✅ Lists valid options, provides concrete example, clear error description
GitHubToolsetValidationError sets the bar:
Success Criteria
skills/validation-error-messages.mdcreatedExpected Outcomes
Priority
High - Establishes foundation for all validation message improvements
Estimated Effort
Medium (1-2 days)
Source
Extracted from Repository Quality Improvement Report #11292 - Validation Message Clarity & Developer Guidance (Task 1)