[delight] UX Analysis 2026-05-30: poem-bot comment & design-decision-gate failure message

[github-actions[bot]]

User Experience Analysis Report — 2026-05-30

Executive Summary

Today's analysis reviewed 2 documentation files, 2 workflow message configurations, and 1 validation test file across gh-aw's user-facing surface.

Overall Quality: Mostly Professional with targeted improvement opportunities.

Key Finding: The poem-bot.md workflow has a misplaced comment that creates a visually confusing YAML structure — readers must mentally reparse the file to understand which config block the comment applies to. A one-line fix eliminates the confusion entirely.

---

Quality Highlights ✅

Highlight 1: GHE Debugging Guide

• File: docs/src/content/docs/troubleshooting/debug-ghe.md
• What works well: Precise prerequisites, numbered setup steps, a comprehensive domain reference table, and Advanced sections that use clear headings. The TIP callout surfacing the single critical config change immediately is excellent progressive disclosure.
• Reference: > [!TIP] The one thing you must do differently from github.com is set api-target...

Highlight 2: Dispatch Workflow Error Messages

• File: pkg/workflow/dispatch_workflow_validation.go (validated by test)
• What works well: Error messages identify the problem, show exactly what was checked, and provide a numbered fix list — a strong pattern for actionable enterprise error messages.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Misplaced Comment in poem-bot Messages Section — Single File Fix

• File: .github/workflows/poem-bot.md
• Current State: Lines ~32–35 contain a comment # Deny all network access sandwiched between the last imports: list item and network: {}, making the YAML visually ambiguous:

  imports:
    - shared/reporting.md
  
  # Deny all network access
    - shared/otlp.md
  network: {}

• Issue: The comment appears to annotate - shared/otlp.md (the imports entry below it) but actually describes network: {} (the key that follows). A reader must trace indentation carefully to understand the structure.
• User Impact: Workflow authors copying or adapting this file may misread the comment's intent, either misattributing shared/otlp.md as a "network access" import or placing network: {} incorrectly in their own workflows.
• Suggested Change: Reorder the comment so it sits directly above network: {}:

  imports:
    - shared/reporting.md
    - shared/otlp.md
  
  # Deny all network access
  network: {}

• Design Principle: Clarity and Precision — YAML structure should match visual intuition without requiring the reader to cross-reference indentation rules.

Medium Priority

Opportunity 2: Ambiguous run-failure Message in design-decision-gate

• File: .github/workflows/design-decision-gate.md
• Current State (messages section):

  run-success: "✅ [{workflow_name}]({run_url}) completed the design decision gate check."
  run-failure: "❌ [{workflow_name}]({run_url}) {status} during design decision gate check."

• Issue: The word "during" implies the check is still in progress rather than complete. The {status} placeholder also produces slightly redundant output (the ❌ already signals failure), and the phrasing is asymmetric with run-success.
• User Impact: Status messages appear in GitHub PR timelines and are the primary signal for enterprise teams deciding whether a PR is blocked. Ambiguous wording increases the chance that a team member reads "during" as "still running" and waits unnecessarily.
• Suggested Change:

  run-failure: "❌ [{workflow_name}]({run_url}) {status} — design decision gate check could not complete."

  The em-dash separates the status token from the human-readable description, matching common enterprise notification conventions.
• Design Principle: Professional Communication — status messages in PR timelines must be unambiguous and scannable at a glance.

---

Files Reviewed

Documentation

• docs/src/content/docs/troubleshooting/debug-ghe.md — Rating: ✅ Professional
• docs/src/content/docs/blog/2026-04-20-weekly-update.md — Rating: ✅ Professional

Workflow Messages

• .github/workflows/poem-bot.md — Rating: ⚠️ Needs Minor Work (misplaced comment)
• .github/workflows/design-decision-gate.md — Rating: ⚠️ Needs Minor Work (ambiguous failure message)

Validation Code

• pkg/workflow/dispatch_workflow_validation_test.go — Rating: ✅ Professional

---

🎯 Actionable Tasks

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

---

Task 1: Fix Misplaced Comment in poem-bot.md

File to Modify: .github/workflows/poem-bot.md

Current Experience

The imports and network sections are visually conflated by a comment placed between the last import entry and the network key:

imports:
  - shared/reporting.md

# Deny all network access
  - shared/otlp.md
network: {}

Quality Issue

Design Principle: Clarity and Precision

Comments in YAML workflows serve as inline documentation for contributors and operators. When a comment appears between list items and the next key, it visually annotates the wrong element, breaking the reader's mental model. Enterprise workflow authors routinely copy-paste frontmatter patterns — a misplaced comment propagates confusion.

Proposed Improvement

Move - shared/otlp.md above the comment so the comment precedes network: {}:

Before:

imports:
  - shared/reporting.md

# Deny all network access
  - shared/otlp.md
network: {}

After:

imports:
  - shared/reporting.md
  - shared/otlp.md

# Deny all network access
network: {}

Why This Matters

• User Impact: Workflow authors adapting this file will immediately understand the structure without tracing indentation
• Quality Factor: Clarity — comment placement should match semantic intent
• Frequency: poem-bot.md is a reference workflow used as a template example

Success Criteria

• Changes made to .github/workflows/poem-bot.md only
• - shared/otlp.md appears as last item in the imports list before the comment
• # Deny all network access comment is the immediate line before network: {}
• Quality rating improves from ⚠️ to ✅

Scope Constraint

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

---

Task 2: Clarify run-failure Message in design-decision-gate.md

File to Modify: .github/workflows/design-decision-gate.md

Current Experience

The run-failure status message uses the word "during" and an asymmetric structure compared to run-success:

run-success: "✅ [{workflow_name}]({run_url}) completed the design decision gate check."
run-failure: "❌ [{workflow_name}]({run_url}) {status} during design decision gate check."

Quality Issue

Design Principle: Professional Communication

"During" implies the event is still in progress. Enterprise PR reviewers scanning a timeline see this message as their go/no-go signal. The current wording may cause a reader to interpret the check as still running rather than having failed. Additionally, the asymmetry with run-success reduces the scannable predictability of the message pair.

Proposed Improvement

Replace "during" with an em-dash construction that clearly frames the outcome as complete:

Before:

run-failure: "❌ [{workflow_name}]({run_url}) {status} during design decision gate check."

After:

run-failure: "❌ [{workflow_name}]({run_url}) {status} — design decision gate check could not complete."

Why This Matters

• User Impact: PR authors and reviewers get an unambiguous signal that the gate finished with a failure, not that it is still running
• Quality Factor: Professional Communication — predictable, scannable status messages
• Frequency: This message appears in every failing design-decision-gate run across all PRs that trigger the workflow

Success Criteria

• Changes made to .github/workflows/design-decision-gate.md only
• run-failure message no longer uses the word "during"
• Message clearly communicates completion, not in-progress state
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/design-decision-gate.md
• No changes to other files required

---

Metrics

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

References: §26687029627

📊 User experience analysis by Delight · sonnet46 4.3M · ◷

• expires on Jun 2, 2026, 3:11 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #36132.