[delight] UX Analysis Report – 2026-06-29

[github-actions[bot]]

User Experience Analysis — 2026-06-29

Files reviewed: 2 docs · 2 CLI sources · 2 workflow message configs · 1 validation file (7 total)

Overall: Mixed — 5 professional, 2 need minor work.

Key Finding: pr-code-quality-reviewer.md success message lacks direction to PR review comments — high-frequency friction on every code review.

---

Quality Highlights ✅

docs/src/content/docs/specs/copilot-sdk-driver-specification.md — Exemplary W3C-style formal spec: numbered ToC, RFC 2119 notation (MUST/SHOULD/MAY), explicit L1/L2/L3 compliance levels. Sets the project documentation standard.

pkg/workflow/template_injection_utils.go — formatTemplateInjectionError is textbook error UX: groups violations by context, shows safe vs. unsafe patterns side-by-side with real YAML, links to three references.

---

Improvement Opportunities 💡

High Priority — .github/workflows/pr-code-quality-reviewer.md

Both status messages leave users without next steps:

# Current
run-success: "✅ [{workflow_name}]({run_url}) completed the code quality review."
run-failure: "⚠️ [{workflow_name}]({run_url}) {status} during code quality review."

# Proposed
run-success: "✅ [{workflow_name}]({run_url}) completed the code quality review. See inline review comments for findings."
run-failure: "⚠️ [{workflow_name}]({run_url}) {status} during code quality review. Check the [run logs]({run_url}) for details."

• run-success: Users see ✅ and may not scroll up to find review comments. Compare approach-validator.md: "Review the report and react with ✅ or ❌."
• run-failure: Missing log link. Compare archie.md: "Check the run logs for details."
• Fires on every PR ready_for_review event — high-frequency touchpoint.

Medium Priority — pkg/workflow/template_injection_utils.go

formatTemplateInjectionError (line 325) says "detected in compiled workflow" but provides no guidance that the fix must go in the SOURCE .md file. Users may waste time editing the generated .lock.yml.

Proposed addition (before References block, line ~366):

builder.WriteString("Fix: Edit your source workflow markdown file (.md) and run gh aw compile to regenerate the lock file.\n\n")

---

Files Reviewed

File	Rating
docs/.../specs/copilot-sdk-driver-specification.md	✅ Professional
docs/.../blog/2026-01-13-meet-the-workflows-issue-management.md	✅ Professional
pkg/cli/add_command.go (gh aw add)	✅ Professional
pkg/cli/audit.go (gh aw audit)	✅ Professional
.github/workflows/daily-fact.md	✅ Professional
.github/workflows/pr-code-quality-reviewer.md	⚠️ Needs Minor Work
pkg/workflow/template_injection_utils.go	⚠️ Needs Minor Work

---

🎯 Actionable Tasks

Task 1 — .github/workflows/pr-code-quality-reviewer.md

Add direction to both status messages (two line change, no recompile required).

Success criteria: run-success references inline review comments; run-failure includes a {run_url} log link.

Task 2 — pkg/workflow/template_injection_utils.go

Insert one builder.WriteString(...) line before the References block in formatTemplateInjectionError directing authors to edit their source .md and rerun gh aw compile.

Success criteria: Error message explicitly names the source .md as the file to edit.

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 · 111.2 AIC · ⌖ 11.5 AIC · ⊞ 8.4K · ◷

• expires on Jul 2, 2026, 8:11 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #42509.