Error Messages

Use this format for gh-aw validation errors. Keep messages clear, actionable, and example-driven.

Error Message Template

Make each error message answer three questions:

1. What’s wrong? - Clearly state the validation error
2. What’s expected? - Explain the valid format or values
3. How to fix it? - Provide a concrete example of correct usage

Constructive Language

Avoid standalone negative wording. Pair it with expected behavior and a concrete fix.

❌ invalid repo format: %s
✅ invalid repo format '%s' — expected 'owner/repo' format (for example: 'github/gh-aw')

❌ not in a git repository
✅ not in a git repository — run 'git init' or 'cd' to a git repository

When to use NewValidationError vs fmt.Errorf

• Use NewValidationError(field, value, reason, suggestion) in *_validation.go logic.
  • Use field for the exact config path
  • Use reason for what failed
  • Use suggestion for an actionable fix with an example
• Use fmt.Errorf for operational/wrapping errors (%w) where you are propagating a lower-level failure with context.
• Avoid generic wrappers like fmt.Errorf("failed to X: %w", err) unless you add recovery guidance.

Suggestion Text Checklist

Every suggestion should:

1. Explain what to change
2. Include a minimal valid YAML/code example
3. Use ✓/✗ markers when ambiguity is likely

Example:

YAML Example Guidelines

• Keep examples minimal and valid YAML
• Use real frontmatter field names
• Quote only when YAML requires it
• Prefer 2-space indentation

Good Examples

These examples follow the template and provide actionable guidance:

Time Delta Validation (from time_delta.go)

✅ Why it’s good:

• Clearly identifies the invalid input
• Lists multiple valid format examples
• Shows combined formats (+1d12h30m)

Type Validation with Example

✅ Why it’s good:

• Shows actual type received (%T)
• Provides concrete YAML example
• Uses proper YAML syntax with quotes

Enum Validation with Options

✅ Why it’s good:

• Lists all valid options
• Provides simplest example
• Uses consistent formatting

MCP Configuration

✅ Why it’s good:

• Explains mutual exclusivity
• Shows realistic tool name
• Formats multi-line YAML example

Bad Examples

These examples lack clarity or actionable guidance:

Too Vague

❌ Problems:

• Doesn’t specify what format is invalid
• Doesn’t explain expected format
• No example provided

Missing Example

❌ Problems:

• States requirement but no example
• User doesn’t know proper YAML syntax
• Could be clearer about type received

Incomplete Information

❌ Problems:

• Doesn’t list valid options
• No guidance on fixing the error
• User must search documentation

When to Include Examples

Always include examples for:

1. Format/Syntax Errors - Show the correct syntax

   goCopy

   fmt.Errorf("invalid date format. Expected: YYYY-MM-DD HH:MM:SS. Example: 2024-01-15 14:30:00")

2. Enum/Choice Fields - List all valid options

   goCopy

   fmt.Errorf("invalid permission level: %s. Valid levels: read, write, none. Example: permissions:\n  contents: read", level)

3. Type Mismatches - Show expected type and example

   goCopy

   fmt.Errorf("timeout-minutes must be an integer, got %T. Example: timeout-minutes: 10", value)

4. Complex Configurations - Provide complete valid example

   goCopy

   fmt.Errorf("invalid MCP server config. Example:\nmcp-servers:\n  my-server:\n    command: \"node\"\n    args: [\"server.js\"]")

When Examples May Be Optional

Examples can be omitted when:

1. Error is from wrapped error - When wrapping another error with context

   goCopy

   return fmt.Errorf("failed to parse configuration: %w", err)

2. Error is self-explanatory with clear context

   goCopy

   return fmt.Errorf("duplicate unit '%s' in time delta: +%s", unit, deltaStr)

3. Error points to specific documentation

   goCopy

   return fmt.Errorf("unsupported feature. See https://docs.example.com/features")

Formatting Guidelines

Use Type Verbs for Dynamic Content

• %s - strings
• %d - integers
• %T - type of value
• %v - general value
• %w - wrapped errors

Multi-line Examples

For YAML configuration examples spanning multiple lines:

Quoting in Examples

Use proper YAML syntax in examples:

Consistent Terminology

Use the same field names as in YAML:

Error Message Testing

All improved error messages should have corresponding tests:

Migration Strategy

When improving existing error messages:

1. Identify the error - Find validation error that lacks clarity
2. Analyze context - Understand what’s being validated
3. Apply template - Add what’s wrong + expected + example
4. Add tests - Verify error message content
5. Update comments - Document the validation logic

Examples by Category

Format Validation

Type Validation

Choice/Enum Validation

Configuration Validation

References

• Excellent example to follow: pkg/workflow/time_delta.go
• Pattern inspiration: Go standard library error messages
• Testing examples: pkg/workflow/*_test.go

Tools

When writing error messages, consider:

• The user’s perspective (what do they need to fix it?)
• The context (where in the workflow is the error?)
• The documentation (should we reference specific docs?)
• The complexity (is multi-line example needed?)