[delight] UX Analysis Report — 2026-07-06

[github-actions[bot]]

User Experience Analysis Report — 2026-07-06

Executive Summary

Today's analysis covered 2 documentation files, 2 workflow message configurations, and 1 validation file.

Overall Quality: ⚠️ Needs Minor Work

Key Finding: The ValidateIncludedPermissions error message in pkg/workflow/permissions_validation.go uses a redundant ERROR: prefix and an ambiguous header phrase, which increases diagnosis time for users encountering permission errors during gh aw compile.

---

Quality Highlights ✅

Cross-Repository Reference (docs/src/content/docs/reference/cross-repository.md): Three clearly-labeled feature categories with working YAML examples for every scenario, a :::note admonition flagging safe-output limitations, and a comprehensive Related Documentation footer. Rating: ✅ Professional

Permissions Error Design (pkg/workflow/permissions_validation.go — formatMissingPermissionsMessage): Two distinct resolution paths (add permissions vs. reduce toolsets) with copy-paste YAML snippets and a direct docs URL. Rating: ✅ (for this function)

---

Improvement Opportunities 💡

High Priority — pkg/workflow/permissions_validation.go

Issue: ValidateIncludedPermissions (line 338) opens with "ERROR: Imported workflows require permissions that are not granted in the main workflow." followed by "The permission set must be explicitly declared in the main workflow." The ERROR: prefix is redundant inside an error return value, and "the permission set" implies all permissions must be re-declared, not just the missing ones.

Before:

errorMsg.WriteString("ERROR: Imported workflows require permissions that are not granted in the main workflow.\n\n")
errorMsg.WriteString("The permission set must be explicitly declared in the main workflow.\n\n")

After:

errorMsg.WriteString("Imported workflow(s) require additional permissions not declared in the main workflow.\n\n")
errorMsg.WriteString("Add the missing permissions to your main workflow's frontmatter:\n\n")

Medium Priority — .github/workflows/necromancer.md

Issue: Line 69 — "is exhuming regressions for this {event_type}..." uses exhuming (recovering buried things) to describe adding new regression tests. Developers unfamiliar with the zombie theme may read this as a bug-discovery signal rather than a prevention step, triggering unnecessary escalation.

Before:

run-started: "🧟 [{workflow_name}]({run_url}) is exhuming regressions for this {event_type}..."

After:

run-started: "🧟 [{workflow_name}]({run_url}) is hunting regressions in this {event_type}..."

---

Files Reviewed

File	Category	Rating
docs/src/content/docs/reference/cross-repository.md	Documentation	✅ Professional
docs/src/content/docs/blog/2026-01-13-meet-the-workflows-continuous-simplicity.md	Documentation	✅ Professional
.github/workflows/outcome-collector.md	Workflow Messages	✅ Professional
.github/workflows/necromancer.md	Workflow Messages	⚠️ Minor Work
pkg/workflow/permissions_validation.go	Validation Code	⚠️ Minor Work

Quality Distribution: ✅ Professional: 3 · ⚠️ Needs Minor Work: 2 · ❌ Needs Significant Work: 0

---

🎯 Actionable Tasks

Task 1 — pkg/workflow/permissions_validation.go

Single file: pkg/workflow/permissions_validation.go

Remove the ERROR: prefix (line 338) and replace "The permission set must be explicitly declared" with "Add the missing permissions to your main workflow's frontmatter:". See Before/After above.

• ERROR: prefix removed
• Second sentence changed from constraint to direct instruction
• No other files modified

Task 2 — .github/workflows/necromancer.md

Single file: .github/workflows/necromancer.md

Change "exhuming regressions" → "hunting regressions" in run-started (line 69). See Before/After above.

• One-word change on line 69 only
• No other messages or files modified

📊 User experience analysis by Delight · 54.1 AIC · ⌖ 8.15 AIC · ⊞ 8.5K · ◷

• expires on Jul 9, 2026, 8:03 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #44579.