[delight] UX Analysis Report — 2026-06-17: Network Docs Wildcard Inconsistency & Recurring Theatrical Messages

[github-actions[bot]]

User Experience Analysis Report — 2026-06-17

Executive Summary

• 2 documentation files analyzed
• 2 workflow message configurations reviewed
• 1 validation file reviewed

Overall Quality: Mixed — documentation and validation are strong; one workflow's messages remain theatrical (recurring, 21 days).

Key Finding: docs/src/content/docs/guides/network-configuration.md has a three-way internal inconsistency in its wildcard/bare-domain documentation that will confuse enterprise users and security reviewers.

---

Quality Highlights ✅

Stale PR Cleanup — Model Status Messages

• File: .github/workflows/stale-pr-cleanup.md — ✅ Professional
• Clear intent-signaling emojis (🧹/✅/❌), actionable failure context, {status} variable included
• run-failure: "❌ Stale PR cleanup failed! [{workflow_name}]({run_url}) {status}. Some PRs may not be processed." — this is the benchmark for workflow messages.

Safe-Outputs Needs Validation — Actionable Errors

• File: pkg/workflow/safe_outputs_needs_validation.go — ✅ Professional
• Error messages name the bad value, state the expectation, and include a concrete example: "safe-outputs.%s: unknown job %q. Expected one of the workflow's custom jobs. Example: safe-outputs.%s: [secrets_fetcher]"

Package Manifest Reference — Clean Reference Doc

• File: docs/src/content/docs/reference/aw-yml-package-manifest.md — ✅ Professional
• Logical field table with inline example comments; links to normative spec.

---

Improvement Opportunities 💡

⚠️ High Priority: Wildcard Domain Inconsistency — network-configuration.md (NEW)

File: docs/src/content/docs/guides/network-configuration.md

Three-way contradiction in lines 64–70:

Line	Statement	Implication
64	"api.example.com" # Matches api.example.com and subdomains	Bare domain = subdomain-inclusive
65	"*.cdn.example.com" # Wildcard: matches any subdomain of cdn.example.com	Wildcard = subdomains only (base excluded)
70	`*.example.com` matches ... and `example.com`	Wildcard also matches base (contradicts line 65)
74	TIP: "Both example.com and *.example.com match subdomains"	Correct summary — but too late

User Impact: Security reviewers reading line 64's comment expect api.example.com to match only that exact host. They may approve network access wider than intended. Line 65 contradicts line 70, so the behavior remains unclear even after reading the section twice.

Design Principle: Clarity and Precision; Trust and Reliability.

❌ High Priority (Recurring, 21 days): Theatrical Messages — dev-hawk.md

File: .github/workflows/dev-hawk.md

All three status messages use hawk metaphors:

• run-started: "🦅 Dev Hawk circles the sky! ... monitoring ... from above..."
• run-success: "🦅 Hawk eyes report! ... has completed reconnaissance. Intel delivered! 🎯"
• run-failure: "🦅 Hawk down! ... {status}. The skies grow quiet..."

User Impact: run-failure provides no actionable guidance. Developers receiving a failure notification see a dramatic metaphor instead of a prompt to investigate. First flagged 2026-05-27.

Design Principle: Professional Communication; Trust and Reliability.

---

🎯 Actionable Tasks

Task 1: Fix Wildcard Domain Documentation — network-configuration.md

File to Modify: docs/src/content/docs/guides/network-configuration.md

Before (lines 57–74):

Add specific domains for your services. Both base domains and wildcard patterns are supported:

    - "api.example.com"        # Matches api.example.com and subdomains
    - "*.cdn.example.com"      # Wildcard: matches any subdomain of cdn.example.com

**Wildcard pattern behavior:**
- `*.example.com` matches `sub.example.com`, `deep.nested.example.com`, and `example.com`
- Only single wildcards at the start are supported (e.g., `*.*.example.com` is invalid)

> [!TIP]
> Both `example.com` and `*.example.com` match subdomains. ...

After:

Add specific domains for your services. gh-aw domain matching is **subdomain-inclusive**:
a bare entry (`api.example.com`) and a wildcard entry (`*.api.example.com`) both match
the specified host **and all its subdomains**. Use the bare form for brevity; use the wildcard
form when you want to make subdomain access explicit in code review.

    - "api.example.com"        # Subdomain-inclusive: api.example.com + all subdomains
    - "*.cdn.example.com"      # Equivalent: cdn.example.com + all subdomains

**Wildcard pattern behavior:**
- Both `example.com` and `*.example.com` match the base domain and all its subdomains
- Only a single wildcard at the start is supported (`*.*.example.com` is not valid)

> [!TIP]
> Use the wildcard form (`*.example.com`) when you want to communicate in code review
> that subdomain access is intentional. Both forms are functionally equivalent.

Success Criteria

• Single file: docs/src/content/docs/guides/network-configuration.md
• Lines 64 and 65 comments are consistent with line 70 bullet
• Non-standard behavior explained before the first example, not after
• Rating improves: ⚠️ → ✅

---

Task 2: Replace Theatrical Status Messages — dev-hawk.md (Recurring — 21 days)

File to Modify: .github/workflows/dev-hawk.md

Before (safe-outputs.messages block):

footer: "> 🦅 *Observed from above by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
run-started: "🦅 Dev Hawk circles the sky! [{workflow_name}]({run_url}) is monitoring this {event_type} from above..."
run-success: "🦅 Hawk eyes report! [{workflow_name}]({run_url}) has completed reconnaissance. Intel delivered! 🎯"
run-failure: "🦅 Hawk down! [{workflow_name}]({run_url}) {status}. The skies grow quiet..."

After:

footer: "> 🦅 *Reported by [{workflow_name}]({run_url})*{ai_credits_suffix}{history_link}"
run-started: "🦅 Dev Hawk: [{workflow_name}]({run_url}) is analyzing {event_type} results..."
run-success: "✅ Dev Hawk: [{workflow_name}]({run_url}) completed analysis. Report posted to PR."
run-failure: "❌ Dev Hawk: [{workflow_name}]({run_url}) {status}. Check the workflow run for details."

Success Criteria

• Single file: .github/workflows/dev-hawk.md
• run-failure uses ❌ and directs users to the workflow run
• run-success uses ✅ consistent with stale-pr-cleanup.md benchmark
• No metaphor language in any message
• Only safe-outputs.messages block changes — no logic, triggers, or body modifications

---

References: §27702189971

Warning

Firewall blocked 1 domain

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

• proxy.golang.org

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

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

📊 User experience analysis by Delight · ◷

• expires on Jun 20, 2026, 8:09 AM UTC-08:00