[delight] UX Analysis 2026-05-24: Architecture Guardian Messages & Permissions Validation Doc Link

[github-actions[bot]]

User Experience Analysis Report - 2026-05-24

Executive Summary

Today's analysis covered:

• 2 documentation files — cross-repository.md and reusing-workflows.mdx
• 2 workflow message configurations — refiner.md and architecture-guardian.md
• 1 validation file — dangerous_permissions_validation.go
• CLI help was inaccessible in this environment (permission constraint)

Overall Quality: Mostly professional with two targeted improvements identified.

Key Finding: Workflow status messages in architecture-guardian.md use consumer-grade language (exclamation-heavy, playful persona) and the failure message provides no actionable guidance — both are avoidable friction for enterprise teams monitoring workflow runs in Slack or GitHub notifications.

---

Quality Highlights ✅

Example 1: Cross-Repository Documentation

• File: docs/src/content/docs/reference/cross-repository.md
• What works well: Comprehensive coverage with clear progressive structure — three distinct feature areas introduced up front, code examples for every configuration pattern, explicit callout for types that don't support target-repo: "*", and a rich Related Documentation section
• Reference: The :::note callout on unsupported safe-output types is well-placed and prevents a class of runtime surprises

Example 2: Dangerous Permissions Validation Error

• File: pkg/workflow/dangerous_permissions_validation.go
• What works well: The error message lists the offending scopes explicitly and provides a ready-to-copy corrected permissions: block — reducing fix time to near-zero for well-known violations

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Unprofessional Tone in Architecture Guardian Messages

• File: .github/workflows/architecture-guardian.md
• Current State (Lines 32–34):

  run-started: "��️ Architecture Guardian online! [...] is scanning code structure on this {event_type}..."
  run-success: "✅ Architecture scan complete! [...] has reviewed code structure. Report delivered! 📋"
  run-failure: "🏛️ Architecture scan failed! [...] {status}. Structure status unknown..."
  

• Issue: "Guardian online!" reads like a game notification. Multiple exclamation marks in run-success feel consumer-grade. The run-failure message ends with "Structure status unknown..." — a vague ellipsis that gives engineers no signal about what to investigate
• User Impact: These messages appear in GitHub PR comments, Slack integrations, and notification feeds monitored by engineering leads. The playful tone erodes confidence in automated tooling for enterprise teams
• Design Principle: Professional Communication — business-appropriate tone, respectful of the user's time

Medium Priority

Opportunity 2: Broken Documentation Link in Dangerous Permissions Error

• File: pkg/workflow/dangerous_permissions_validation.go
• Current State (Line 83):

  lines = append(lines, "which uses a scoped GitHub App token. See: docs/safe-outputs.md")

• Issue: docs/safe-outputs.md is a relative filesystem path, not a URL. A user encountering this error in a CI log cannot click or navigate to the referenced document
• User Impact: Forces developers to manually search for the correct documentation page, adding friction during an already disruptive compile-time failure
• Design Principle: Efficiency and Productivity — direct paths to outcomes; eliminate unnecessary steps

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/cross-repository.md — Rating: ✅ Professional
• docs/src/content/docs/guides/reusing-workflows.mdx — Rating: ✅ Professional

CLI Commands

• N/A — binary execution was restricted in this environment

Workflow Messages

• .github/workflows/refiner.md — Rating: ⚠️ Needs Minor Work (tone slightly casual but acceptable)
• .github/workflows/architecture-guardian.md — Rating: ❌ Needs Significant Work

Validation Code

• pkg/workflow/dangerous_permissions_validation.go — Rating: ⚠️ Needs Minor Work

---

Metrics

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

---

🎯 Actionable Tasks

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

---

Task 1: Professionalize Architecture Guardian Status Messages

File to Modify: .github/workflows/architecture-guardian.md

Current Experience

Lines 32–34 of the workflow use animated/playful language:

run-started: "🏛️ Architecture Guardian online! [{workflow_name}]({run_url}) is scanning code structure on this {event_type}..."
run-success: "✅ Architecture scan complete! [{workflow_name}]({run_url}) has reviewed code structure. Report delivered! 📋"
run-failure: "🏛️ Architecture scan failed! [{workflow_name}]({run_url}) {status}. Structure status unknown..."

Quality Issue

Design Principle: Professional Communication

"Guardian online!" mimics a system alert or game character. The success message fires two exclamation marks and an unrelated clipboard emoji. The failure message provides no remediation hint — "Structure status unknown" tells engineers nothing actionable.

Proposed Improvement

run-started: "��️ Architecture Guardian: reviewing code structure for {event_type} — [{workflow_name}]({run_url})"
run-success: "✅ Architecture review complete — [{workflow_name}]({run_url}) has analyzed code structure. See the comment below for the full report."
run-failure: "❌ Architecture review failed ({status}) — [{workflow_name}]({run_url}). Check the [workflow run]({run_url}) for logs."

Why This Matters

• User Impact: Messages appear in PR timelines and Slack feeds; clear, calm language builds trust and reduces noise
• Quality Factor: Professional Communication — business-appropriate, respectful of user expertise
• Frequency: Fires on every pull request and push event

Success Criteria

• Changes made to .github/workflows/architecture-guardian.md only
• No exclamation marks in run-failure message
• run-failure includes a link to workflow run logs
• Quality rating improves from ❌ to ✅

Scope Constraint

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

---

Task 2: Replace Broken Doc Path with Actionable URL in Permissions Validation Error

File to Modify: pkg/workflow/dangerous_permissions_validation.go

Current Experience

Line 83 references a relative filesystem path that does not resolve in a CI log context:

lines = append(lines, "which uses a scoped GitHub App token. See: docs/safe-outputs.md")

Quality Issue

Design Principle: Efficiency and Productivity

A user encountering this error in CI output sees See: docs/safe-outputs.md with no way to navigate there. The correct docs URL is `(ghaw.github.io/redacted) (or equivalent hosted docs URL). Even a GitHub repository path would be more useful than the bare relative path.

Proposed Improvement

lines = append(lines, "which uses a scoped GitHub App token.")
lines = append(lines, "See https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/safe-outputs.md")

Or if a canonical hosted docs URL is available:

lines = append(lines, "which uses a scoped GitHub App token. See: (ghaw.github.io/redacted)

Why This Matters

• User Impact: Developers hitting this error during compilation can immediately open the documentation without searching
• Quality Factor: Efficiency — direct path to resolution
• Frequency: Every developer who adds a write permission to a workflow frontmatter will see this error

Success Criteria

• Changes made to pkg/workflow/dangerous_permissions_validation.go only
• See: reference is a valid, clickable URL
• URL opens to the safe-outputs documentation
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: pkg/workflow/dangerous_permissions_validation.go
• No changes to other files required

---

References:

• §26364621151

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

• expires on May 27, 2026, 3:07 PM UTC

[github-actions[bot]]

💥 WHOOSH! 🦸♂️

The Smoke Test Agent has BLAZED through this discussion thread! ⚡️

🔥 KABOOM! — All Claude engines firing on all cylinders!
✨ ZIP-ZAP! — Safe outputs delivered with surgical precision!
🚀 VOOM! — Run §26365437982 hit the bullseye!

🦾 "Smoke testing has never looked so good!" — Your friendly neighborhood Claude bot 🤖💨

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

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

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

💥 [THE END] — Illustrated by Smoke Claude · opus47 9.3M · ◷