[delight] UX Analysis Report — 2026-04-03

[github-actions[bot]]

Executive Summary

Today's targeted analysis reviewed 4 areas across 7 files:

• 2 documentation files
• 2 CLI commands (from source)
• 2 workflow message configurations
• 1 validation file

Overall Quality: ✅ Professional — the codebase demonstrates strong UX discipline in error messages, CLI help text, and structured workflow messages.

Key Finding: The permissions.md reference page carries a misleading title ("GitHub Tools Read Permissions") that creates navigation confusion for users trying to configure their workflow's permissions: field. A title and intro clarification would significantly reduce friction for new users.

---

Quality Highlights ✅

Example 1: Exemplary CLI Help Text — logs command

• File: pkg/cli/logs_command.go
• What works well: The logs command help text is a model for the rest of the codebase. It organizes 20+ examples into labelled categories (Basic usage, Date filtering, Content filtering, Run ID range filtering, Output options, Cross-repository). Each example is aligned and annotated. The Long description explains exactly what artifacts are produced.
• Quote: Downloaded artifacts include:\n- aw_info.json: Engine configuration and workflow metadata\n- safe_output.jsonl: Agent's final output content...

Example 2: Actionable Engine Error Messages — engine_validation.go

• File: pkg/workflow/engine_validation.go
• What works well: Every error message follows the gold standard: states the problem → lists valid options → provides an inline YAML example → links to documentation. The "Did you mean?" fuzzy matching reduces frustration for typos.
• Quote: "inline engine definition references unknown runtime.id: %s. Known runtime IDs are: %s.\n\nDid you mean: %s?\n\nExample:\nengine:\n runtime:\n id: codex\n\nSee: %s"

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Misleading Document Title — permissions.md

• File: docs/src/content/docs/reference/permissions.md
• Current State: Title is "GitHub Tools Read Permissions" (frontmatter title: field, line 2). The document actually covers the complete permissions: frontmatter field including both read and write contexts (notably id-token: write is covered in its own section). The intro code example juxtaposes permissions: and safe-outputs: without explaining they are separate top-level frontmatter keys. There is no mention of what the default permissions are when the field is omitted entirely.
• Issue: The title "GitHub Tools Read Permissions" reads as documentation about GitHub Tools' own read permissions rather than how to configure the permissions: field in your workflow. This creates a navigation dead-end: users searching for "how do I configure permissions" are unlikely to find this page, and users who land on it may not realise it covers their use case.
• User Impact: New users configuring their first workflow may skip this page or miss the id-token section because the title implies read-only scope.
• Suggested Change: Rename the title to "Configuring Permissions" and description to "Configure GitHub Actions token permissions for agentic workflows". Add a single sentence clarifying the default state when permissions: is omitted, and label the intro code block with a comment.
• Design Principle: Clarity and Precision — users should be able to predict a page's content from its title.

Medium Priority

Opportunity 2: Typo in Security FAQ Answer — faq.md

• File: docs/src/content/docs/reference/faq.md
• Current State: Line 173 reads: "See the [Security Architectur](/gh-aw/introduction/architecture/) for details." — the word "Architecture" is truncated to "Architectur".
• Issue: The broken word reduces professional credibility and could confuse readers skimming link text.
• User Impact: Low functional impact, but visible in a high-traffic FAQ page that many new users will read first.
• Suggested Change: Fix "Architectur" → "Architecture" on that single line.
• Design Principle: Trust and Reliability — accurate, polished content builds confidence.

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/permissions.md — Rating: ⚠️ Needs Minor Work (title mismatch, missing defaults context)
• docs/src/content/docs/reference/faq.md — Rating: ⚠️ Needs Minor Work (one typo, otherwise thorough)

CLI Commands

• pkg/cli/logs_command.go (logs) — Rating: ✅ Professional
• pkg/cli/validate_command.go (validate) — Rating: ✅ Professional

Workflow Messages

• .github/workflows/ci-doctor.md — Rating: ✅ Professional (medical theme is consistent)
• .github/workflows/breaking-change-checker.md — Rating: ✅ Professional

Validation Code

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

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Improve permissions.md — Fix Title and Add Default Permissions Context

File to Modify: docs/src/content/docs/reference/permissions.md

Current Experience

The page title is "GitHub Tools Read Permissions" (frontmatter title: on line 2) with description "Configure GitHub Actions permissions for agentic workflows". The intro paragraph says "read-only permissions by default" but never states what those defaults are. The opening code block places permissions: and safe-outputs: next to each other without clarifying they are separate top-level keys.

Quality Issue

Design Principle: Clarity and Precision

The title "GitHub Tools Read Permissions" is ambiguous — it sounds like documentation about what read permissions GitHub Tools have, not a guide to the permissions: frontmatter field. Enterprise users scanning the reference sidebar will not know this page covers write-permission scenarios (like id-token: write).

Proposed Improvement

Before (lines 1–17):

---
title: GitHub Tools Read Permissions
description: Configure GitHub Actions permissions for agentic workflows
sidebar:
  order: 500
---

The `permissions:` section controls what GitHub API operations your workflow can perform. GitHub Agentic Workflows uses read-only permissions by default for security, with write operations handled through [safe outputs](/gh-aw/reference/safe-outputs/).

```yaml wrap
permissions:
  contents: read
  actions: read
safe-outputs:
  create-issue:
  add-comment:

**After**:

---

title: Configuring Permissions
description: Configure GitHub Actions token permissions for agentic workflows
sidebar:
order: 500

The permissions: frontmatter field controls which GitHub API scopes the workflow token can access. GitHub Agentic Workflows defaults to read-only permissions for security; write operations are handled through safe outputs.

When permissions: is omitted, the workflow inherits the repository's default token permissions (typically contents: read).

# permissions: and safe-outputs: are separate top-level frontmatter keys
permissions:
  contents: read
  actions: read
safe-outputs:
  create-issue:
  add-comment:

**Why This Matters**
- **User Impact**: Correct title improves discoverability via sidebar navigation and search; the added default-state sentence prevents "why did my workflow fail without permissions configured?" support questions.
- **Quality Factor**: Clarity and Precision
- **Frequency**: Every new user configuring their first workflow will read this page.

**Success Criteria**
- [ ] Changes made to `docs/src/content/docs/reference/permissions.md` only
- [ ] Title updated from "GitHub Tools Read Permissions" to "Configuring Permissions"
- [ ] Default permissions behaviour documented in one sentence
- [ ] Code block labelled to distinguish `permissions:` from `safe-outputs:`
- [ ] Quality rating improves from ⚠️ to ✅

**Scope Constraint**
- **Single file only**: `docs/src/content/docs/reference/permissions.md`

---

#### Task 2: Fix Typo in `faq.md` — "Architectur" → "Architecture"

**File to Modify**: `docs/src/content/docs/reference/faq.md`

**Current Experience**

Line 173 reads:

See the Security Architectur for details.

The link text "Security Architectur" is a truncated word — "Architecture" is missing the trailing 'e'.

**Quality Issue**

**Design Principle**: Trust and Reliability

A visible spelling error in the FAQ — one of the most-read reference pages — reduces the perceived quality of the documentation. Link text errors are particularly noticeable.

**Proposed Improvement**

**Before** (line 173):

See the Security Architectur for details.

**After**:

See the Security Architecture for details.

**Why This Matters**
- **User Impact**: Polished, error-free documentation builds trust with enterprise users evaluating the tool.
- **Quality Factor**: Trust and Reliability
- **Frequency**: The FAQ is typically among the first pages read by new users.

**Success Criteria**
- [ ] Changes made to `docs/src/content/docs/reference/faq.md` only
- [ ] "Architectur" corrected to "Architecture" on line 173
- [ ] Quality rating improves from ⚠️ to ✅

**Scope Constraint**
- **Single file only**: `docs/src/content/docs/reference/faq.md`

---

**References:**
- [Workflow run §23945504632](https://github.com/github/gh-aw/actions/runs/23945504632)


<!-- gh-aw-tracker-id: delight-daily -->


> AI generated by [Delight](https://github.com/github/gh-aw/actions/runs/23945504632) · [history](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Fdelight%22&type=discussions)
> - [x] expires <!-- gh-aw-expires: 2026-04-06T12:10:07.153Z --> on Apr 6, 2026, 12:10 PM UTC

<!-- gh-aw-workflow-id: delight -->
<!-- gh-aw-workflow-call-id: github/gh-aw/delight -->

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #24475.