[delight] UX Analysis Report — 2026-04-14

[github-actions[bot]]

Executive Summary

Today's analysis covered 4 categories:

• 2 documentation files (tools.md, triggers.md)
• 1 CLI command (gh aw logs)
• 1 workflow message configuration (archie.md)
• 1 validation file (permissions_validation.go)

Overall Quality: Mostly professional — documentation is well-structured, CLI help text is thorough, and workflow messages follow a consistent voice.

Key Finding: A redundant ERROR: prefix inside an error message in permissions_validation.go creates a double-prefix in user-facing output; and a dense single-sentence options summary in tools.md reduces scannability for a high-traffic reference page.

---

Quality Highlights ✅

docs/src/content/docs/reference/tools.md

Well-structured reference page with consistent per-tool code blocks, clear timeout configuration section, and thorough cross-referencing to deeper documentation. The heading hierarchy and short descriptions per tool (e.g., bash:, playwright:) make quick scanning easy.

pkg/cli/logs_command.go — gh aw logs

Outstanding example coverage organized in clearly labeled groups (# Date filtering, # Content filtering, # Output options). The large number of examples is appropriate given the command's many flags, and inline comments keep them self-documenting. Short description is precise and informative.

.github/workflows/archie.md — Messages

Clear status progression from run-started → run-success → run-failure. The failure message correctly includes a link to run logs (Check the [run logs]({run_url})), making diagnosis immediately actionable. Emoji usage is restrained and purposeful.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Redundant ERROR: prefix in permission validation error — permissions_validation.go

• File: pkg/workflow/permissions_validation.go
• Current State (line 293):

  errorMsg.WriteString("ERROR: Imported workflows require permissions that are not granted in the main workflow.\n\n")

• Issue: The string "ERROR: " is embedded inside an error message that is itself returned as a Go error. The caller in compiler_orchestrator_engine.go (line 202) then wraps it:

  return nil, fmt.Errorf("permission validation failed: %w", err)
  ```
  After console formatting, the user sees something like:
  ```
  ✗ permission validation failed: ERROR: Imported workflows require permissions...

  The ERROR: prefix is redundant and creates a jarring double-label.
• User Impact: The duplicate prefix looks unprofessional and reduces clarity of an already complex message for enterprise users configuring imported workflows.
• Suggested Change: Remove the "ERROR: " prefix, starting the message directly with the actionable sentence.
• Design Principle: Professional Communication — clear, non-redundant language respectful of the reader's time.

Medium Priority

Opportunity 2: Dense "Options" sentence in Custom MCP Servers — tools.md

• File: docs/src/content/docs/reference/tools.md
• Current State (line 174):

  Options: `command` + `args` (process-based), `container` (Docker image), `url` + `headers` (HTTP endpoint), `registry` (MCP registry URI), `env` (environment variables), `allowed` (tool restrictions). See MCPs Guide for setup.

• Issue: Six distinct configuration options are packed into a single sentence with type annotations in parentheses. To find a specific option (e.g., url), users must read the entire sentence. The rest of the file uses bulleted lists for this pattern.
• User Impact: Enterprise users integrating MCP servers need to quickly locate specific fields; the dense format slows down discovery and lookup.
• Suggested Change: Convert to a bulleted list matching the file's style conventions.
• Design Principle: Efficiency and Productivity — reduce cognitive load; enable expert users to scan quickly.

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/tools.md — Rating: ⚠️ Needs Minor Work
• docs/src/content/docs/reference/triggers.md — Rating: ✅ Professional

CLI Commands

• gh aw logs (pkg/cli/logs_command.go) — Rating: ✅ Professional

Workflow Messages

• .github/workflows/archie.md — Rating: ✅ Professional

Validation Code

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

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Remove redundant ERROR: prefix — pkg/workflow/permissions_validation.go

File to Modify: pkg/workflow/permissions_validation.go

Current Experience

Line 293 prefixes the error message body with "ERROR: " — a string-level label that is redundant because the value is already returned as a Go error and then wrapped by the caller with "permission validation failed: ". The terminal output with console formatting shows:

✗ permission validation failed: ERROR: Imported workflows require permissions that are not granted in the main workflow.

Quality Issue

Design Principle: Professional Communication

The double-label (permission validation failed: ERROR:) is redundant, visually jarring, and violates the single-responsibility of error messages: the error type itself signals "this is an error"; the message should focus on what went wrong and how to fix it.

Proposed Improvement

Remove the "ERROR: " string prefix from line 293.

Before:

errorMsg.WriteString("ERROR: Imported workflows require permissions that are not granted in the main workflow.\n\n")

After:

errorMsg.WriteString("Imported workflows require permissions that are not granted in the main workflow.\n\n")

Why This Matters

• User Impact: Cleaner, more professional error output for users running gh aw compile with imported workflows
• Quality Factor: Removes redundant label that conflicts with console formatting layer
• Frequency: Triggered any time a workflow imports components with stricter permission requirements

Success Criteria

• Change made to pkg/workflow/permissions_validation.go only
• ERROR: prefix removed from line 293
• Error message still clearly describes the problem (no loss of information)
• make test-unit passes
• Rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: pkg/workflow/permissions_validation.go

---

Task 2: Convert Custom MCP Servers options to a bulleted list — docs/src/content/docs/reference/tools.md

File to Modify: docs/src/content/docs/reference/tools.md

Current Experience

Line 174 summarizes Custom MCP Server configuration options as a dense inline sentence immediately following the YAML code block:

Options: command + args (process-based), container (Docker image), url + headers (HTTP endpoint), registry (MCP registry URI), env (environment variables), allowed (tool restrictions). See MCPs Guide for setup.

Quality Issue

Design Principle: Efficiency and Productivity

Six configuration options in one sentence require users to parse the entire line to identify a specific field. The rest of tools.md uses short code blocks and clear subheadings per option. The MCP section breaks this pattern.

Proposed Improvement

Replace the dense sentence with a scannable bulleted list.

Before:

**Options**: `command` + `args` (process-based), `container` (Docker image), `url` + `headers` (HTTP endpoint), `registry` (MCP registry URI), `env` (environment variables), `allowed` (tool restrictions). See [MCPs Guide](/gh-aw/guides/mcps/) for setup.

After:

**Configuration options:**
- `command` + `args` — process-based stdio server
- `container` — Docker image
- `url` + `headers` — HTTP endpoint
- `registry` — MCP registry URI (informational; does not affect execution)
- `env` — environment variables
- `allowed` — restrict which tools the server may call

See [MCPs Guide](/gh-aw/guides/mcps/) for setup and examples.

Why This Matters

• User Impact: Users integrating Slack, Jira, or other MCP servers can immediately spot the field they need without reading the full sentence
• Quality Factor: Matches the scanning-friendly format used for all other tools in the file
• Frequency: The Custom MCP Servers section is a key entry point for enterprise integrations

Success Criteria

• Change made to docs/src/content/docs/reference/tools.md only
• Bulleted list replaces the dense options sentence
• All 6 options preserved with accurate descriptions
• Link to MCPs Guide retained
• Rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/reference/tools.md

---

References: §24398099314

📊 User experience analysis by Delight · ● 1.2M · ◷

• expires on Apr 17, 2026, 12:17 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #26419.