UX Analysis Report – 2026-03-24: Workflow Messages Tone & Validation Error Clarity

[github-actions[bot]]

Today's delight analysis focused on 4 categories of user-facing content, targeting high-traffic, high-impact files.

Files Reviewed

Category	File	Rating
Documentation	docs/src/content/docs/setup/quick-start.mdx	✅ Professional
Documentation	docs/src/content/docs/troubleshooting/common-issues.md	✅ Professional
CLI Command	pkg/cli/add_command.go	✅ Professional
CLI Command	pkg/cli/fix_command.go	✅ Professional
Workflow Messages	.github/workflows/archie.md	⚠️ Needs Minor Work
Workflow Messages	.github/workflows/brave.md	❌ Needs Significant Work
Validation Code	pkg/workflow/agent_validation.go	⚠️ Needs Minor Work

Quality Highlights ✅

Documentation: common-issues.md

• What works well: Structured with ## sections by failure domain, each issue has a clear Error Message → Cause → Solution pattern, and solutions include inline code examples and links to official GitHub docs.
• Reference: "Add github/gh-aw@* to your organization's allowed actions list" with exact navigation path and YAML example — exactly what an enterprise admin needs.

CLI Help: add_command.go

• What works well: 8 distinct examples covering all major use cases (repo import, versioned import, URL form, local file, wildcard), with inline comments explaining each variant. Workflow specification format is explicitly documented.
• Reference: gh aw add githubnext/agentics/ci-doctor --create-pull-request --force # PR with overwrite

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Casual/Game-Like Tone in brave.md Messages

• File: .github/workflows/brave.md
• Current State (frontmatter messages block):

  run-started: "🔍 Brave Search activated! [{workflow_name}]({run_url}) is venturing into the web on this {event_type}..."
  run-success: "🦁 Mission accomplished! [{workflow_name}]({run_url}) has returned with the findings. Knowledge acquired! 🏆"
  run-failure: "🔍 Search interrupted! [{workflow_name}]({run_url}) {status}. The web remains unexplored..."

• Issue: The language is playful and game-like ("venturing into the web", "Knowledge acquired! 🏆", "The web remains unexplored..."). This tone is inappropriate for enterprise contexts where managers, security teams, and stakeholders may see these messages in GitHub issue comments.
• User Impact: Enterprise users may perceive these messages as unprofessional, reducing trust in the automation tool. The failure message in particular is actively unhelpful — "The web remains unexplored..." provides zero actionable information and may appear dismissive of a real failure.
• Design Principle: Professional Communication — messages should be business-appropriate, respectful of user expertise, and frame failures with actionable guidance rather than whimsy.

Medium Priority

Opportunity 2: Redundant & Non-Actionable Error Messages in agent_validation.go

• File: pkg/workflow/agent_validation.go
• Current State (lines 119 and 143):

  // Line 119
  return fmt.Errorf("max-turns not supported: engine '%s' does not support the max-turns feature", engine.GetID())
  
  // Line 143
  return fmt.Errorf("max-continuations not supported: engine '%s' does not support the max-continuations feature", engine.GetID())

• Issue: Both messages are redundant — the phrase "not supported" appears twice, once in the prefix and once in the body. More critically, neither message tells the user what they can do about it. For max-turns, only Claude supports it; for max-continuations, only Copilot supports it. This information would directly help the user fix the problem.
• User Impact: A developer sees this error during gh aw compile and must independently research which engine supports the feature — a friction-creating, time-wasting experience.
• Design Principle: Efficiency and Productivity — error messages should provide direct paths to resolution without requiring external research.

---

🎯 Actionable Tasks

Task 1: Tone Improvement — .github/workflows/brave.md

File to Modify: .github/workflows/brave.md

Current Experience

The messages section in the frontmatter (lines ~21-25) uses playful, game-like language inappropriate for enterprise context:

Before:

run-started: "🔍 Brave Search activated! [{workflow_name}]({run_url}) is venturing into the web on this {event_type}..."
run-success: "🦁 Mission accomplished! [{workflow_name}]({run_url}) has returned with the findings. Knowledge acquired! 🏆"
run-failure: "🔍 Search interrupted! [{workflow_name}]({run_url}) {status}. The web remains unexplored..."

After:

run-started: "🔍 [{workflow_name}]({run_url}) is searching the web for this {event_type}..."
run-success: "🔍 [{workflow_name}]({run_url}) completed the web search and posted results. ✅"
run-failure: "🔍 [{workflow_name}]({run_url}) encountered an issue during the web search. Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Messages appear in GitHub issue comments visible to the entire team, including non-technical stakeholders. Professional tone builds trust.
• Quality Factor: Professional Communication — business-appropriate, actionable on failure.
• Frequency: Every /brave slash command invocation produces these messages.

Success Criteria

• Changes made to .github/workflows/brave.md only
• run-failure message now includes actionable guidance (link to run logs)
• Quality rating improves from ❌ to ✅

Scope Constraint

• Single file only: .github/workflows/brave.md
• No changes to compiled .lock.yml required beyond recompile (messages are evaluated at runtime, not compile time)

---

Task 2: Error Message Clarity — pkg/workflow/agent_validation.go

File to Modify: pkg/workflow/agent_validation.go

Current Experience

Lines 119 and 143 emit error messages that are redundant and provide no resolution guidance:

Before (line 119):

return fmt.Errorf("max-turns not supported: engine '%s' does not support the max-turns feature", engine.GetID())

Before (line 143):

return fmt.Errorf("max-continuations not supported: engine '%s' does not support the max-continuations feature", engine.GetID())

After (line 119):

return fmt.Errorf("engine '%s' does not support max-turns. Switch to 'engine: claude' to use max-turns, or remove the max-turns setting", engine.GetID())

After (line 143):

return fmt.Errorf("engine '%s' does not support max-continuations. Switch to 'engine: copilot' to use max-continuations, or remove the max-continuations setting", engine.GetID())

Why This Matters

• User Impact: Developers get clear guidance during gh aw compile — they know exactly which engine to switch to, saving research time.
• Quality Factor: Clear error messages with actionable solutions; removes redundancy.
• Frequency: Encountered during workflow compilation whenever an unsupported engine+feature combination is used.

Success Criteria

• Changes made to pkg/workflow/agent_validation.go only
• Both error messages (lines 119 and 143) updated
• No "not supported: ... does not support" redundancy remains
• Each message names a supported engine alternative

Scope Constraint

• Single file only: pkg/workflow/agent_validation.go
• No test changes required (messages are tested by checking error string contents; adjust if needed)

---

Metrics

• Files Analyzed: 7
• Quality Distribution:
  • ✅ Professional: 4
  • ⚠️ Needs Minor Work: 2 (archie.md, agent_validation.go)
  • ❌ Needs Significant Work: 1 (brave.md)

References: §23488467227

AI generated by Delight · history

• expires on Mar 31, 2026, 12:10 PM UTC

[github-actions[bot]]

💥 WHOOSH!

⚡ ZAP! POW! KABOOM! ⚡

The smoke test agent has arrived! 🦸

AGENT CLAUDE-23489532394 swooped through this discussion like a superhero through Gotham — and the smoke test passed with flying colors!

🔥 All systems: NOMINAL
🚀 Engine: CLAUDE
💪 Status: MIGHTY AND UNSTOPPABLE

"With great agentic power comes great automated responsibility!"

— The Smoke Test Agent 💨

💥 [THE END] — Illustrated by Smoke Claude · ◷