[delight] User Experience Analysis Report – 2026-06-28

[github-actions[bot]]

Executive Summary

Today’s analysis focused on:

• 2 documentation files
• 2 CLI commands (compile, run)
• 2 workflow message configurations
• 1 validation file (test)

Overall Quality: Mixed — CLI help text and reference documentation are professional; workflow status messages show addressable inconsistencies.

Key Finding: archie.md switches emoji mid-lifecycle (📐 start → 🎨 success → 📐 failure), breaking consistent status identity — an instance of the theatrical-message anti-pattern previously identified in smoke-pi.md and architecture-guardian.md.

---

Quality Highlights ✅

compile command — Exemplary Help Text

• File: cmd/gh-aw/main.go
• What works well: The Long description provides a precise three-flag matrix (--action-mode, --action-tag, --gh-aw-ref) with mutual-exclusivity rules and real use cases. The 7+ examples cover interactive mode, file paths, directories, and edge cases.
• Quote: "--gh-aw-ref <branch-tag-or-sha> — Resolve a branch name, tag, or SHA from github/gh-aw to its full commit SHA at compile time and pin the compiled workflow to that immutable SHA."

copilot-cloud-agent.mdx — Structured Reference Documentation

• File: docs/src/content/docs/reference/copilot-cloud-agent.mdx
• What works well: Clear two-output structure (create-agent-session / assign-to-agent), inline YAML config examples, dedicated authentication section with token-creation deep links, and a video walkthrough for the PAT creation flow.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Inconsistent Emoji Identity in Archie Messages — archie.md

• File: .github/workflows/archie.md
• Current State (lines 34–36 of the messages block):

  run-started: "📐 [{workflow_name}]({run_url}) is analyzing the architecture..."
  run-success:  "🎨 [{workflow_name}]({run_url}) has completed the architecture visualization. ✅"
  run-failure:  "📐 [{workflow_name}]({run_url}) encountered an issue..."
  

• Issue: The in-progress and failure states share 📐 while success switches to 🎨. This emoji hop creates ambiguity about which emoji represents Archie. The workflow’s declared emoji is 🏛️ (in frontmatter), making none of the three message emojis canonical.
• User Impact: Enterprise users scanning GitHub issue timelines use emoji as fast visual anchors. An inconsistent anchor forces users to re-read the full message to determine which workflow posted it.
• Design Principle: Trust and Reliability — consistent experience across touchpoints.

Medium Priority

Opportunity 2: Missing Log Link in Failure Message — impeccable-skills-reviewer.md

• File: .github/workflows/impeccable-skills-reviewer.md
• Current State (line 102):

  run-failure: "🧵 [{workflow_name}]({run_url}) {status} during the skills-based review."
  

• Issue: The message omits an actionable next step. The {status} placeholder yields text like "failed during the skills-based review" with no link to diagnostic information. Compare to archie.md’s more helpful failure message: "Check the run logs for details."
• User Impact: When a PR review workflow fails, developers need to reach the run log immediately. Making them hunt for the link wastes time and reduces trust in the tool.
• Design Principle: Efficiency and Productivity — direct paths to outcomes.

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/copilot-cloud-agent.mdx — Rating: ✅ Professional
• docs/src/content/docs/blog/2026-01-13-meet-the-workflows-continuous-improvement.md — Rating: ✅ Professional (blog format; github.github.com URLs are correct per astro.config.mjs)

CLI Commands

• gh aw compile — Rating: ✅ Professional
• gh aw run — Rating: ✅ Professional

Workflow Messages

• .github/workflows/archie.md — Rating: ⚠️ Needs Minor Work
• .github/workflows/impeccable-skills-reviewer.md — Rating: ⚠️ Needs Minor Work

Validation Code

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

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: Normalize Status Emoji — .github/workflows/archie.md

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

Current Experience

The messages block (lines ~32–37) uses three different emojis across four message types:

footer:      "> 📊 *Diagram rendered by ...*"
run-started: "📐 [{workflow_name}]({run_url}) is analyzing..."
run-success: "🎨 [{workflow_name}]({run_url}) has completed..."
run-failure: "📐 [{workflow_name}]({run_url}) encountered an issue..."

The workflow’s declared emoji is 🏛️ (architecture/archive symbol), which appears nowhere in the status messages.

Quality Issue

Design Principle: Trust and Reliability — consistent experience across touchpoints.

Users scanning a thread expect a single visual marker to identify the workflow. The 📐→🎨→📐 sequence breaks that expectation and continues the theatrical-emoji anti-pattern flagged in previous runs (smoke-pi.md, architecture-guardian.md).

Proposed Improvement

Align all status messages to use 🏛️ — the workflow’s declared identity emoji:

Before:

messages:
  footer: "> 📊 *Diagram rendered by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
  run-started: "📐 [{workflow_name}]({run_url}) is analyzing the architecture for this {event_type}..."
  run-success: "🎨 [{workflow_name}]({run_url}) has completed the architecture visualization. ✅"
  run-failure: "📐 [{workflow_name}]({run_url}) encountered an issue and could not complete the architecture diagram. Check the [run logs]({run_url}) for details."

After:

messages:
  footer: "> 🏛️ *Diagram rendered by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
  run-started: "🏛️ [{workflow_name}]({run_url}) is analyzing the architecture for this {event_type}..."
  run-success: "🏛️ [{workflow_name}]({run_url}) has completed the architecture visualization. ✅"
  run-failure: "🏛️ [{workflow_name}]({run_url}) encountered an issue and could not complete the architecture diagram. Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Consistent emoji lets users instantly identify Archie’s comments in busy issue threads without reading the full message text.
• Quality Factor: Predictable behavior / consistent identity across status states.
• Frequency: Every Archie invocation posts at least one status message.

Success Criteria

• Changes made to .github/workflows/archie.md only
• All four message keys (footer, run-started, run-success, run-failure) use the same emoji
• Emoji matches the emoji: field in the workflow frontmatter
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/archie.md
• No changes to lock file or other workflows required

---

Task 2: Add Log Link to Failure Message — .github/workflows/impeccable-skills-reviewer.md

File to Modify: .github/workflows/impeccable-skills-reviewer.md

Current Experience

Line 102 of the messages block:

run-failure: "🧵 [{workflow_name}]({run_url}) {status} during the skills-based review."

This renders as, for example:

🧵 Impeccable Skills Reviewer failed during the skills-based review.

Quality Issue

Design Principle: Efficiency and Productivity — provide direct paths to outcomes.

When a PR review workflow fails, the developer’s first action is to check the run log. The current message requires them to find and click the {run_url} embedded in the workflow name hyperlink — which is not obvious. archie.md and other workflows already use the explicit pattern: Check the [run logs]({run_url}) for details.

Proposed Improvement

Before:

run-failure: "🧵 [{workflow_name}]({run_url}) {status} during the skills-based review."

After:

run-failure: "🧵 [{workflow_name}]({run_url}) {status} during the skills-based review. Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Developers on a deadline can immediately navigate to the failure log from the PR comment.
• Quality Factor: Actionable guidance in error states.
• Frequency: Every failed skills-review run (network issues, external skills unavailable, etc.) surfaces this message.

Success Criteria

• Changes made to .github/workflows/impeccable-skills-reviewer.md only
• run-failure message ends with an explicit log link
• Consistent with the failure message pattern in archie.md and other reviewed workflows
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/impeccable-skills-reviewer.md
• No changes to lock file or other workflows required

---

References:

• Workflow Run §28326409435

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• storage.googleapis.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "storage.googleapis.com"

See Network Configuration for more information.

📊 User experience analysis by Delight · 70.6 AIC · ⌖ 8.46 AIC · ⊞ 8.4K · ◷

• expires on Jul 1, 2026, 7:13 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #42288.