[delight] User Experience Analysis Report — 2026-07-12

[github-actions[bot]]

Executive Summary

Today's analysis focused on:

• 2 documentation file(s)
• 2 CLI command(s)
• 0 workflow message configurations (workflow samples were inaccessible due to tool permissions)
• 1 validation file

Overall Quality: ✅ Professional — the codebase maintains a high standard across most user-facing touchpoints.

Key Finding: docs/src/content/docs/guides/agentic-authoring.mdx contains several informal phrases that reduce the professional tone of the documentation, such as "surely fail" and first-person possessives like "our authoring agent" and "our structure".

---

Quality Highlights ✅

Example 1: Validation Error Messages — pkg/workflow/safe_outputs_steps_shell_expansion_validation.go

• File: pkg/workflow/safe_outputs_steps_shell_expansion_validation.go
• What works well: Error messages are precise, actionable, and professional. They identify the specific step index, describe the dangerous pattern category, show an offending code snippet, and provide a concrete fix strategy.
• Quote/Reference: "safe-outputs.steps[%d]: run script contains %s, which is blocked by the safe-outputs security harness at runtime\n\n Offending snippet: %s\n\nAvoid command substitution, backticks, indirect expansion, and parameter transformation in safe-outputs run scripts. Write URL values and other dynamic content to files in /tmp/gh-aw/agent/ during the agent turn, then read the file contents in the safe-outputs step"

Example 2: CLI Help — pkg/cli/audit.go

• File: pkg/cli/audit.go
• What works well: The audit command provides 5 real-world examples spanning run IDs, full URLs, job-scoped URLs, step-specific anchors, and GitHub Enterprise Server URLs — comprehensive coverage for an enterprise audience.
• Quote/Reference: Short: "Audit workflow runs and generate detailed reports" with examples for every common URL format.

---

Improvement Opportunities 💡

High Priority Details

High Priority

Opportunity 1: Informal Language in Agentic Authoring Guide — Single File Improvement

• File: docs/src/content/docs/guides/agentic-authoring.mdx
• Current State:
  • Line 10: Using our authoring agent is an effective way to create, debug, optimize your agentic workflows.
  • Line 39: On the first run in a new repository, the workflow will surely fail because the secrets are not configured.
  • Line 49 (code block): Adapt permissions and repository-specific references for our structure.
  • Line 89 (code block): Create a workflow that triages new issues and have it run on our self-hosted runners (runs-on: self-hosted).
• Issue: First-person possessives (our authoring agent, our structure, our self-hosted runners) blur the boundary between the product and the reader's organization. The word surely in a tip callout sounds casual and slightly negative (implying failure is inevitable rather than explaining a prerequisite).
• User Impact: Enterprise users reading documentation expect neutral, precise technical writing. First-person possessives create ambiguity about ownership, and casual language (surely fail) can reduce trust in the product's reliability perception.
• Suggested Change: Replace informal phrasing with precise, neutral language.
• Design Principle: Professional Communication + Clarity and Precision

---

Files Reviewed

Documentation

• docs/src/content/docs/guides/agentic-authoring.mdx — Rating: ⚠️ Needs Minor Work
• docs/src/content/docs/reference/copilot-cloud-agent.mdx — Rating: ✅ Professional

CLI Commands

• gh aw audit — Rating: ✅ Professional
• gh aw fix — Rating: ✅ Professional

Validation Code

• pkg/workflow/safe_outputs_steps_shell_expansion_validation.go — Rating: ✅ Professional

---

Metrics

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

---

🎯 Actionable Tasks

Here is 1 targeted improvement task affecting a single file:

Task 1: Improve Tone Professionalism — docs/src/content/docs/guides/agentic-authoring.mdx

File to Modify: docs/src/content/docs/guides/agentic-authoring.mdx

Current Experience

Several phrases use informal first-person possessives and casual language that are inconsistent with enterprise-grade technical documentation:

• Line 10: Using our authoring agent is an effective way to create, debug, optimize your agentic workflows.
• Line 39 (TIP callout): On the first run in a new repository, the workflow will surely fail because the secrets are not configured.
• Line 49 (example prompt block): Adapt permissions and repository-specific references for our structure.
• Line 89 (example prompt block): ...have it run on our self-hosted runners (runs-on: self-hosted).

Quality Issue

Design Principle: Professional Communication

First-person plurals (our authoring agent, our structure) are ambiguous — readers do not know if our refers to the GitHub team or the reader's own organization. The word surely in a tip callout is conversational and carries an unintentionally pessimistic tone.

Proposed Improvement

Before (line 10):

Using our authoring agent is an effective way to create, debug, optimize your agentic workflows.

After:

The authoring agent is an effective way to create, debug, and optimize agentic workflows.

Before (line 39):

On the first run in a new repository, the workflow will surely fail because the secrets are not configured.

After:

On the first run in a new repository, the workflow will fail because the required secrets have not yet been configured.

Before (line 49 example prompt):

Adapt permissions and repository-specific references for our structure.

After:

Adapt permissions and repository-specific references for this repository.

Before (line 89 example prompt):

Create a workflow that triages new issues and have it run on our self-hosted runners (runs-on: self-hosted).

After:

Create a workflow that triages new issues and run it on self-hosted runners (runs-on: self-hosted).

Why This Matters

• User Impact: Removes ambiguity about organizational ownership; neutral tone signals the documentation is authoritative and product-focused.
• Quality Factor: Professional Communication — enterprise users expect precise, third-person technical language.
• Frequency: This is the primary guide for agentic authoring, likely one of the highest-traffic pages in the documentation.

Success Criteria

• Changes made to docs/src/content/docs/guides/agentic-authoring.mdx only
• No first-person possessives (our) remaining in prose sections
• surely replaced with neutral phrasing
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/guides/agentic-authoring.mdx
• No changes to other files required
• Can be completed independently

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 · 32.2 AIC · ⌖ 7.46 AIC · ⊞ 8.4K · ◷

• expires on Jul 15, 2026, 7:05 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #45287.