UX Analysis Report – 2026-03-01

[github-actions[bot]]

Today's analysis covered 7 files across documentation, CLI help text, workflow messages, and validation code. The overall quality is professional, with two targeted improvement opportunities identified — each scoped to a single file.

Executive Summary

• Documentation files reviewed: 2
• CLI commands reviewed: 2
• Workflow message configurations reviewed: 2
• Validation files reviewed: 1

Overall Quality: ✅ Professional with minor friction points

Key Finding: The brave.md workflow messages use a gamified narrative tone that is inconsistent with professional enterprise deployments — and the failure message provides no actionable guidance to users.

---

Quality Highlights ✅

Highlight 1: MCP Getting Started Guide

• File: docs/src/content/docs/guides/getting-started-mcp.md
• What works well: Excellent progressive disclosure — the guide flows from Quick Start (5 minutes) → Configuration Patterns → Custom Servers → Debugging → Troubleshooting. The toolset comparison table (line 68–75) is a clear, scannable decision aid. The three practical examples reflect real enterprise use cases (issue triage, PR review with CI data, multi-service security audit).
• Reference: Step 1 through Step 2 sequence effectively lowers the barrier to first use with minimal prerequisites.

Highlight 2: Logs Command Help Text

• File: pkg/cli/logs_command.go
• What works well: The Long: description is comprehensive without being overwhelming — it lists artifact types, includes relative date syntax (--start-date -1w), and organizes examples into logical groups (basic, date filtering). The artifact list gives users a clear mental model of what will be downloaded.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Inconsistent and Unhelpful Failure Message – Single File Improvement

• File: .github/workflows/brave.md
• Current State (lines 27–30):

  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 run-success message ("Mission accomplished! Knowledge acquired! 🏆") and run-failure message ("The web remains unexplored...") adopt a gamified narrative tone. More critically, the failure message provides zero actionable information — it doesn't direct users to check logs or take any corrective action.
• User Impact: These messages appear in GitHub issue and PR comments visible to all team members and stakeholders. The narrative framing reduces trust in the system and the failure message leaves users with no path forward.
• Design Principle: Trust and Reliability — users need clear status and actionable guidance, especially on failure.

Medium Priority

Opportunity 2: Unactionable Engine Capability Error Messages – Single File Improvement

• File: pkg/workflow/agent_validation.go
• Current State (lines 117, 138):

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

• Issue: Both errors tell users what went wrong but not how to fix it. The user must search documentation to discover that max-turns requires the claude engine and max-continuations requires the copilot engine.
• User Impact: Developers hit these errors during compilation and must leave the terminal to search for the correct engine name, breaking their workflow.
• Design Principle: Clarity and Precision — error messages should include the corrective action.

---

Files Reviewed

Documentation

• docs/src/content/docs/guides/getting-started-mcp.md — Rating: ✅ Professional
• docs/src/content/docs/reference/frontmatter.md — Rating: ✅ Professional

CLI Commands

• pkg/cli/checks_command.go — Rating: ✅ Professional
• pkg/cli/logs_command.go — Rating: ✅ Professional

Workflow Messages

• .github/workflows/archie.md — Rating: ✅ Professional
• .github/workflows/brave.md — Rating: ⚠️ Needs Minor Work

Validation Code

• pkg/workflow/agent_validation.go — Rating: ⚠️ Needs Minor Work

---

Metrics

• Files Analyzed: 7
• Quality Distribution:
  • ✅ Professional: 5
  • ⚠️ Needs Minor Work: 2
  • ❌ Needs Significant Work: 0

---

🎯 Actionable Tasks

Here are 2 targeted improvement tasks, each affecting a single file:

---

Task 1: Improve Failure Message Tone in brave.md

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

Current Experience

Lines 27–30 contain messages with a gamified narrative that is inconsistent with professional deployments. The failure message provides no actionable guidance:

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..."

Quality Issue

Design Principle: Trust and Reliability — clear status and actionable failure guidance

The run-failure message uses a narrative phrase ("The web remains unexplored...") that obscures system state and provides no recovery path. Compare to archie.md which says "Check the run logs for details." — a direct, helpful instruction.

Proposed Improvement

# Before:
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-success: "🔍 [{workflow_name}]({run_url}) completed the web search. ✅"
run-failure: "🔍 [{workflow_name}]({run_url}) encountered an issue and could not complete the search. Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Failure messages visible to all stakeholders now provide a clear next step
• Quality Factor: Consistency with other professional workflows (archie, ci-doctor pattern)
• Frequency: Appears in every workflow execution visible in GitHub comment threads

Success Criteria

• Changes made to .github/workflows/brave.md only
• Failure message includes actionable link to run logs
• Tone is consistent with other workflow messages in the repository
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/brave.md
• No changes to other files required

---

Task 2: Add Actionable Guidance to Engine Capability Errors in agent_validation.go

File to Modify: pkg/workflow/agent_validation.go

Current Experience

Lines 117 and 138 produce errors when users configure unsupported features for the wrong engine:

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

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

Quality Issue

Design Principle: Clarity and Precision — errors should include the corrective action

The error tells users the problem but not the solution. A developer using engine: codex with max-turns set will only learn it's unsupported — not that switching to engine: claude resolves it.

Proposed Improvement

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

// Line 117 — After:
return fmt.Errorf("max-turns is not supported by engine '%s'. Use 'engine: claude' in your workflow frontmatter to enable max-turns control", engine.GetID())

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

// Line 138 — After:
return fmt.Errorf("max-continuations is not supported by engine '%s'. Use 'engine: copilot' in your workflow frontmatter to enable max-continuations control", engine.GetID())

Why This Matters

• User Impact: Developers get the fix inline in their terminal without leaving the workflow compile step
• Quality Factor: Error messages go from diagnostic to actionable
• Frequency: Triggered every time a user misconfigures engine-specific features — a common mistake when learning the platform

Success Criteria

• Changes made to pkg/workflow/agent_validation.go only
• Each error message names the supported engine explicitly
• Phrasing is consistent with existing error message style in the file
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: pkg/workflow/agent_validation.go
• No changes to other files required

---

References:

• §22542456121

AI generated by Delight

• expires on Mar 8, 2026, 11:33 AM UTC