[delight] User Experience Analysis Report - 2026-08-28

[github-actions[bot]]

Executive Summary

Today's analysis focused on:

• 2 documentation files (docs/src/content/docs/blog/2026-08-19-agent-of-the-day.md, docs/src/content/docs/reference/gh-aw-as-mcp-server.md)
• 2 workflow message configurations (.github/workflows/cloclo.md, .github/workflows/necromancer.md)
• 1 validation file (pkg/workflow/name_validation.go)

Overall Quality: Largely professional, with one notable exception in status-message tone.

Key Finding: The cloclo.md workflow's user-facing status messages (run-started, run-success, run-failure, footer) and its "Be Glamorous" response guidance lean heavily into theatrical language ("Comme d'habitude!", "Bravo!", "Intermission...") that may read as unprofessional or confusing to enterprise users scanning PR/issue notifications for actionable status.

Quality Highlights ✅

Example 1: MCP Server Reference Documentation

• File: docs/src/content/docs/reference/gh-aw-as-mcp-server.md
• What works well: Clear structural hierarchy (Configuration Options → Available Tools table → per-client setup), concrete code samples for every client (Copilot CLI, VS Code, Docker), and a well-organized tools table with Purpose/Key options/Returns columns. Callouts ([!WARNING], [!NOTE]) precisely state security/caching caveats (e.g., "never falls back to open access if GITHUB_ACTOR is missing").
• Quote/Reference: "When validation is enabled, logs, audit, and audit-diff require write, maintain, or admin access... never falls back to open access if GITHUB_ACTOR is missing."

Example 2: Name Validation Error Messages

• File: pkg/workflow/name_validation.go
• What works well: Error messages state the problem, the exact invalid value, the rule, and a corrected example in one line: invalid npm package name: %q — npm names must be lowercase alphanumeric... (e.g. "my-package" or "@scope/name"). This matches enterprise error-message best practice: clear problem, actionable fix, example.

Improvement Opportunities 💡

High Priority

Opportunity 1: Tone Down Theatrical Status Messages in cloclo.md

• File: .github/workflows/cloclo.md
• Current State: Lines ~50-53 define safe-outputs.messages:
  • footer: "> 🎤 *Magnifique! Performance by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
  • run-started: "🎵 Comme d'habitude! [{workflow_name}]({run_url}) takes the stage on this {event_type}..."
  • run-success: "🎤 Bravo! [{workflow_name}]({run_url}) has delivered a stunning performance! Standing ovation! 🌟"
  • run-failure: "🎵 Intermission... [{workflow_name}]({run_url}) {status}. Check the [run logs]({run_url}) for details."
• Issue: These messages appear as GitHub status comments on real issues/PRs/discussions. run-failure's "Intermission..." obscures that the run actually failed — a user scanning notifications could miss that action is needed. The persona-driven language ("Bravo!", "Standing ovation!") is charming but inconsistent with the otherwise professional tone of sibling workflows (e.g., necromancer.md).
• User Impact: Enterprise users triaging many bot comments need to immediately distinguish success/failure at a glance; theatrical phrasing adds a decoding step and risks the failure message being skimmed past.
• Suggested Change: Keep the persona flavor but lead each message with an unambiguous status word/emoji (✅/⚠️) before the themed text, e.g.:
  • run-failure: "⚠️ Failed: [{workflow_name}]({run_url}) {status}. Check the [run logs]({run_url}) for details."
  • run-success: "✅ Success: [{workflow_name}]({run_url}) completed. 🎤 Bravo!"
• Design Principle: Clarity and Precision; Trust and Reliability (clear, unambiguous status communication).

Files Reviewed

Documentation

• docs/src/content/docs/blog/2026-08-19-agent-of-the-day.md - Rating: ✅
• docs/src/content/docs/reference/gh-aw-as-mcp-server.md - Rating: ✅

Workflow Messages

• .github/workflows/cloclo.md - Rating: ⚠️ Needs Minor Work
• .github/workflows/necromancer.md - Rating: ✅

Validation Code

• pkg/workflow/name_validation.go - Rating: ✅

Metrics

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

🎯 Actionable Tasks

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

Task 1: Clarify Failure Status in Cloclo Workflow Messages

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

Current Experience

The safe-outputs.messages block (around lines 50-53) uses purely thematic language for status updates that are posted as real GitHub comments on issues, PRs, and discussions:

messages:
  footer: "> 🎤 *Magnifique! Performance by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
  run-started: "🎵 Comme d'habitude! [{workflow_name}]({run_url}) takes the stage on this {event_type}..."
  run-success: "🎤 Bravo! [{workflow_name}]({run_url}) has delivered a stunning performance! Standing ovation! 🌟"
  run-failure: "🎵 Intermission... [{workflow_name}]({run_url}) {status}. Check the [run logs]({run_url}) for details."

Quality Issue

Design Principle: Clarity and Precision / Trust and Reliability

The run-failure message ("Intermission...") does not clearly signal failure. A user scanning multiple bot comments across issues could misread this as a normal pause rather than an error requiring attention, reducing trust and increasing time-to-detect for failed runs.

Proposed Improvement

Prefix each message with an unambiguous status marker while preserving the workflow's persona for flavor.

Before:

  run-success: "🎤 Bravo! [{workflow_name}]({run_url}) has delivered a stunning performance! Standing ovation! 🌟"
  run-failure: "🎵 Intermission... [{workflow_name}]({run_url}) {status}. Check the [run logs]({run_url}) for details."

After:

  run-success: "✅ Success — 🎤 Bravo! [{workflow_name}]({run_url}) has delivered a stunning performance! Standing ovation! 🌟"
  run-failure: "⚠️ Failed — 🎵 Intermission for [{workflow_name}]({run_url}): {status}. Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Users can immediately triage success vs. failure without parsing themed language.
• Quality Factor: Clarity and Trust
• Frequency: Every /cloclo invocation posts one of these messages as a status comment.

Success Criteria

• Changes made to .github/workflows/cloclo.md only (frontmatter messages block)
• run-failure and run-success messages start with an unambiguous status word/emoji
• Quality rating improves from ⚠️ to ✅
• gh aw compile runs clean after the change (recompile the .lock.yml)

Scope Constraint

• Single file only: .github/workflows/cloclo.md
• No changes to other files required (note: compiling will regenerate the paired .lock.yml, which is expected/generated output, not a manual edit)
• Can be completed independently

📊 User experience analysis by Delight · copilot · auto · 23.6 AIC · ⌖ 6.94 AIC · ⊞ 12.3K · ◷

• expires on Aug 31, 2026, 10:54 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #56907.