[delight] User Experience Analysis Report - 2026-07-13

[github-actions[bot]]

Executive Summary

Today's analysis focused on:

• 2 documentation files
• 2 CLI commands
• 2 workflow configurations
• 1 validation file

Overall Quality: Mostly Professional — two files need targeted improvements.

Key Finding: The rate-limiting-controls.md reference doc buries its Best Practices and Troubleshooting sections in prose walls, reducing scannability for enterprise users who need to act quickly.

---

Quality Highlights ✅

Example 1: Strict Mode Validation Error Messages

• File: pkg/workflow/strict_mode_validation_test.go
• What works well: Each strict-mode error message includes the specific permission name, a security rationale, and a concrete list of alternative safe-outputs operations — the actionable guidance pattern done right.
• Quote: "strict mode: write permission 'contents: write' is not allowed for security reasons. Use 'safe-outputs.create-issue', 'safe-outputs.create-pull-request', 'safe-outputs.add-comment', or 'safe-outputs.update-issue' to perform write operations safely"

Example 2: compile Command Long Description

• File: cmd/gh-aw/main.go
• What works well: Clearly separates three action-mode flags with structured sub-bullets, provides a rich Example block with 8 concrete invocations, and notes mutual-exclusivity constraints up front.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Prose walls in Best Practices and Troubleshooting — single file

• File: docs/src/content/docs/reference/rate-limiting-controls.md
• Issue: Both sections are undivided prose paragraphs. The Troubleshooting section has three distinct failure scenarios run together without separation.
• User Impact: Enterprise operators responding to incidents must scan quickly. Prose walls force full reads, increasing time-to-resolution.
• Design Principle: Efficiency and Productivity — minimize cognitive load.

Medium Priority

Opportunity 2: Broken Quick Start URL in blog post — single file

• File: docs/src/content/docs/blog/2026-01-13-meet-the-workflows-issue-management.md
• Issue: Quick Start links use https://github.github.com/gh-aw/setup/quick-start/ (duplicated hostname). Three occurrences.
• User Impact: New adopters following the blog series hit a dead link and abandon onboarding.
• Design Principle: Trust and Reliability — accurate information.

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/rate-limiting-controls.md — ⚠️ Needs Minor Work
• docs/src/content/docs/blog/2026-01-13-meet-the-workflows-issue-management.md — ⚠️ Needs Minor Work

CLI Commands

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

Workflow Configurations

• .github/workflows/unbloat-docs.md — ✅ Professional
• .github/workflows/issue-monster.md — ✅ Professional

Validation Code

• pkg/workflow/strict_mode_validation_test.go — ✅ Professional

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Improve Scannability of Best Practices & Troubleshooting

File to Modify: docs/src/content/docs/reference/rate-limiting-controls.md

Design Principle: Efficiency and Productivity

The "Best Practices" and "Troubleshooting" sections are prose paragraphs. Operators responding to live issues need to locate the relevant entry at a glance.

Before (Best Practices):

Start with conservative limits and increase as needed. Use environments for high-risk operations ... Layer multiple controls ... Monitor workflow runs ...

After (Best Practices):

- **Start conservative**: Begin with lower limits and increase based on observed usage.
- **Use environments for high-risk operations**: Require manual approval for workflow dispatches, cross-repo operations, and production systems.
- **Layer multiple controls**: Combine rate limiting with concurrency, timeouts with `stop-after`, and safe output limits with environments.
- **Monitor actively**: Review workflow run logs, safe output audit logs, and rate limit cancellations to tune configuration.

Before (Troubleshooting):

**Workflow immediately cancelled**: Check rate limit in pre-activation logs, verify concurrency queue, or confirm stop-after hasn't exceeded.

**Agent assignments slow**: Built-in 10-second delays are intentional. Five agents = ~40 seconds total.

**Workflow dispatch not triggering**: Verify max dispatch limit (default: 1), check 5-second delay, confirm target workflow has `on: workflow_dispatch`, or check pending environment approvals.

After (Troubleshooting) — convert to a table:

| Symptom | Likely Cause | Resolution |
|---------|-------------|------------|
| Workflow immediately cancelled | Rate limit exceeded, full concurrency queue, or `stop-after` elapsed | Check pre-activation logs; inspect concurrency queue; verify `stop-after` value |
| Agent assignments are slow | Built-in 10-second delay per assignment | Expected — 5 agents ≈ 40 seconds total |
| Workflow dispatch not triggering | `max` limit reached, delay in progress, missing trigger, or pending approval | Verify `max` (default: 1); confirm target workflow has `on: workflow_dispatch`; review environment approvals |

Success Criteria

• docs/src/content/docs/reference/rate-limiting-controls.md only
• Best Practices converted to bulleted list
• Troubleshooting converted to structured table
• Quality rating: ⚠️ → ✅

---

Task 2: Fix Broken Quick Start URLs

File to Modify: docs/src/content/docs/blog/2026-01-13-meet-the-workflows-issue-management.md

Design Principle: Trust and Reliability

Three Quick Start links use https://github.github.com/gh-aw/setup/quick-start/ (duplicated hostname), which will not resolve. This breaks the onboarding path for new adopters arriving via the blog series.

Before:

[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)

After (use verified canonical URL or site-relative path):

[Quick Start](/gh-aw/setup/quick-start/)

Three occurrences to fix in the "Using These Workflows" and "Learn More" sections.

Success Criteria

• docs/src/content/docs/blog/2026-01-13-meet-the-workflows-issue-management.md only
• All three Quick Start links corrected
• Quality rating: ⚠️ → ✅

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 · 43.6 AIC · ⌖ 4.97 AIC · ⊞ 8.4K · ◷

• expires on Jul 16, 2026, 7:44 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-16T15:44:18.572Z.

Closed by Workflow