[delight] UX Analysis Report — April 11, 2026

[github-actions[bot]]

Executive Summary

Today's analysis focused on:

• 1 documentation file (docs/src/content/docs/setup/quick-start.mdx)
• 1 CLI command (the run command in cmd/gh-aw/main.go)
• 1 workflow message configuration (.github/workflows/brave.md)
• 1 validation file (pkg/workflow/expression_syntax_validation.go)

Overall Quality: Mostly professional — strong technical accuracy throughout, with two targeted wording improvements that would meaningfully raise the bar for enterprise users.

Key Finding: The Quick Start guide's closing section uses informal, personal-name-referencing copy ("Peli's Agent Factory") that feels out of place in enterprise documentation and may undermine user trust.

---

Quality Highlights ✅

Expression Syntax Validation — Exemplary Error Messages

• File: pkg/workflow/expression_syntax_validation.go
• What works well: Every error path provides (1) a precise problem statement, (2) character-position context, (3) a concrete fix instruction, and (4) an inline example where helpful.
• Quote: "Provide a valid GitHub Actions expression inside '$\{\{ }}'. Example: '$\{\{ github.ref }}'" — this is the gold standard for actionable error messages.

run Command — Comprehensive Examples

• File: cmd/gh-aw/main.go (runCmd)
• What works well: 10+ concrete examples covering interactive mode, branch overrides, repeat runs, input passing, push-before-run, and dry-run. Users can find the pattern they need instantly.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Informal Closing Section in Quick Start — Single File

• File: docs/src/content/docs/setup/quick-start.mdx (lines 119–127)
• Current State:

  ## What's next?
  
  There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of
  these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).
  

• Issue: Three separate enterprise-tone problems in two lines:
  1. ## What's next? — casual phrasing; enterprise docs conventionally use "Next Steps" or "Continue Learning"
  2. There are hundreds of other ways...! — exclamation mark signals marketing copy, not technical documentation
  3. Peli's Agent Factory — personal possessive name as a link label. New users have no context for who "Peli" is; the label reveals nothing about destination content
• User Impact: Enterprise users evaluating the product see an unprofessional closing. It breaks the polished tone established by the rest of the page and may trigger procurement-review concerns.
• Suggested Change:

  ## Next Steps
  
  Explore additional workflow examples and use cases in the [Agent Factory showcase](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).
  ```

• Design Principle: Professional Communication — avoid personal references and informal punctuation in enterprise documentation

Medium Priority

Opportunity 2: Ambiguous Prerequisite in run Help Text — Single File

• File: cmd/gh-aw/main.go (runCmd, line 369)
• Current State:

  The workflows must have been added as actions and compiled.
  

• Issue: "added as actions" is ambiguous. It could mean "added as GitHub Actions composite actions", "registered as GitHub Actions workflows", or simply "placed in .github/workflows/". A user encountering this for the first time has no reliable way to interpret it without going to external docs.
• User Impact: New users attempting gh aw run after only reading the help text may be confused about the prerequisite. They may attempt to run a workflow that hasn't been compiled, or search for an "add as action" command that doesn't exist.
• Suggested Change:

  Workflow Markdown files must exist in `.github/workflows/` and be compiled to YAML (via `gh aw compile`) before running.
  

• Design Principle: Clarity and Precision — prerequisites should be explicit and unambiguous

---

Files Reviewed

Documentation

• docs/src/content/docs/setup/quick-start.mdx — Rating: ⚠️ Needs Minor Work

CLI Commands

• gh aw run (cmd/gh-aw/main.go) — Rating: ⚠️ Needs Minor Work

Workflow Messages

• .github/workflows/brave.md — Rating: ✅ Professional

Validation Code

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

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Improve Quick Start Closing Section — quick-start.mdx

File to Modify: docs/src/content/docs/setup/quick-start.mdx

Current Experience

Lines 119–127 close the Quick Start guide with an informal tone that is inconsistent with the professional register of the rest of the page.

Quality Issue

Design Principle: Professional Communication

Three issues compound in just two lines: a casual heading, an exclamation-mark-terminated marketing sentence, and a link label that is a personal possessive name unknown to the reader.

Proposed Improvement

Before (lines 119–127):

## What's next?

There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).

Continue learning with these resources:

- [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/)
- [How Agentic Workflows Work](/gh-aw/introduction/how-they-work/)
- [Frequently Asked Questions](/gh-aw/reference/faq/)

After:

## Next Steps

Explore additional workflow examples and use cases in the [Agent Factory showcase](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).

Continue learning with these resources:

- [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/)
- [How Agentic Workflows Work](/gh-aw/introduction/how-they-work/)
- [Frequently Asked Questions](/gh-aw/reference/faq/)
```

**Why This Matters**
- **User Impact**: Enterprise users and procurement reviewers see a consistent professional voice from first word to last
- **Quality Factor**: Professional Communication — formal yet approachable, without personal references
- **Frequency**: Quick Start is the highest-traffic page in the documentation; every new user reads it

**Success Criteria**
- [ ] Changes made to `docs/src/content/docs/setup/quick-start.mdx` only
- [ ] Heading changed from `## What's next?` to `## Next Steps`
- [ ] Link text changed from `Peli's Agent Factory` to `Agent Factory showcase`
- [ ] Exclamation mark sentence revised to declarative tone
- [ ] Quality rating improves from ⚠️ to ✅

**Scope Constraint**
- **Single file only**: `docs/src/content/docs/setup/quick-start.mdx`
- No changes to other files required
- Can be completed independently in under 5 minutes

---

#### Task 2: Clarify Run Command Prerequisite — `cmd/gh-aw/main.go`

**File to Modify**: `cmd/gh-aw/main.go`

**Current Experience**

The `run` command's `Long` description (line 369) contains an ambiguous prerequisite statement that new users cannot reliably interpret from the help text alone.

**Quality Issue**

**Design Principle**: Clarity and Precision

"Added as actions" does not map to any user-visible operation. The CLI has `gh aw compile` but no `gh aw add-as-action` command. First-time users cannot determine from this line alone what they must do before running.

**Proposed Improvement**

**Before (line 369):**
```
The workflows must have been added as actions and compiled.
```

**After:**
```
Workflow Markdown files must exist in `.github/workflows/` and be compiled to YAML (via `gh aw compile`) before running.

Why This Matters

• User Impact: New users can follow the exact prerequisite path without consulting external documentation
• Quality Factor: Efficiency and Productivity — users get to a successful gh aw run faster
• Frequency: run is the primary execution command; its help text is read every time a user is unsure

Success Criteria

• Changes made to cmd/gh-aw/main.go only
• The prerequisite statement is explicit about the file path and references gh aw compile
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: cmd/gh-aw/main.go
• No changes to other files required
• Can be completed independently

---

References: §24281993768

📊 User experience analysis by Delight · ● 1.7M · ◷

• expires on Apr 14, 2026, 12:05 PM UTC

[github-actions[bot]]

💥 WHOOSH! 🦸

POW! — The smoke test agent has swooped in! BAM!

🤖 SMOKE TEST AGENT WAS HERE 🤖

Run 24282404926 — Claude engine fully operational!

"With great agentic power comes great workflow responsibility!" — Claude, probably

KA-BOOM! 💥 All systems nominal! The agent continues its endless vigil... swoosh

💥 [THE END] — Illustrated by Smoke Claude · ● 202.5K · ◷

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #26025.