[delight] UX Analysis — 2026-04-24

[github-actions[bot]]

Executive Summary

Today's analysis focused on:

• 1 documentation file (docs/src/content/docs/reference/faq.md)
• 1 workflow message configuration (approach-validator.md)
• 1 validation file (pkg/workflow/engine_validation.go)

Overall Quality: Predominantly professional with two targeted improvement opportunities.

Key Finding: The FAQ's security section contains a broken hyperlink (typo "Security Architectur") that silently renders a dead link — undermining trust precisely where users expect the highest accuracy.

---

Quality Highlights ✅

Highlight 1: Engine validation error messages

• File: pkg/workflow/engine_validation.go
• What works well: Every error message includes (1) a clear problem statement naming the invalid value, (2) all valid alternatives, (3) an inline copy-paste YAML example, and (4) a docs URL. The validateEngineInlineDefinition function adds "Did you mean?" suggestions via fuzzy matching.
• Reference: "inline engine definition references unknown runtime.id: %s. Known runtime IDs are: %s.\n\nDid you mean: %s?"

Highlight 2: FAQ depth and structure

• File: docs/src/content/docs/reference/faq.md
• What works well: The FAQ covers an exceptionally wide scope (determinism, guardrails, costs, workflow design) and consistently closes each answer with a "See [X]" cross-reference link. The balance between brevity and completeness is well calibrated for an enterprise audience.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Broken hyperlink in the security FAQ section

• File: docs/src/content/docs/reference/faq.md
• Current State (line 173): See the [Security Architectur](/gh-aw/introduction/architecture/) for details.
• Issue: Missing trailing e in the link text creates a visually odd broken label. The same link elsewhere in the file correctly reads "Security Architecture" (lines 217, 226).
• User Impact: Enterprise security teams read this section closely. A misspelled link in the secrets/permissions answer signals sloppiness in the most trust-sensitive part of the FAQ.
• Suggested Change: See the [Security Architecture](/gh-aw/introduction/architecture/) for details.
• Design Principle: Trust and Reliability — consistent, accurate information

Medium Priority

Opportunity 2: Casual phrasing in the CI trigger answer

• File: docs/src/content/docs/reference/faq.md
• Current State (line 403): "The easy way to fix this problem is to set a secret GH_AW_CI_TRIGGER_TOKEN with a Personal Access Token (PAT) with 'Contents: Read & Write' permission to your repo."
• Issue: "The easy way" is a conversational hedge out of place in a reference FAQ. It implies an unstated "hard way" without explaining it, which can create confusion. "to your repo" is overly colloquial next to the formal preceding paragraphs.
• User Impact: The answer reads as rushed when enterprise users often need precise instructions they can follow in an audit trail.
• Suggested Change: Rephrase to: "To enable CI checks, add a repository secret named \GH_AW_CI_TRIGGER_TOKEN` containing a Personal Access Token (PAT) with Contents: Read & Write permission for the repository."`
• Design Principle: Professional Communication — consistent, precise language

Opportunity 3: run-failure message exposes raw status placeholder

• File: .github/workflows/approach-validator.md
• Current State (line 49): run-failure: "❌ [{workflow_name}]({run_url}) {status} during approach validation."
• Issue: The {status} interpolation renders the raw GitHub Actions conclusion string (e.g., failure, timed_out, cancelled). These are internal identifiers, not user-facing language. A timed_out run produces "❌ Approach Validator timed_out during approach validation." — awkward prose.
• User Impact: Reduces credibility of the notification; reviewers seeing timed_out must mentally map a technical token to its meaning.
• Suggested Change: Replace the {status} interpolation with fixed, human-readable text: run-failure: "❌ [{workflow_name}]({run_url}) did not complete approach validation. Check the run log for details."
• Design Principle: Professional Communication — clear status information

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/faq.md — Rating: ⚠️ Needs Minor Work (one broken link, one informal sentence)

Workflow Messages

• .github/workflows/approach-validator.md — Rating: ⚠️ Needs Minor Work (run-failure exposes raw status token)

Validation Code

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

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Fix broken hyperlink and informal phrasing — docs/src/content/docs/reference/faq.md

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

Current Experience

Line 173 has a misspelled hyperlink (Security Architectur) that silently fails.
Line 403 uses conversational phrasing (The easy way to fix this problem) inconsistent with the surrounding enterprise-grade text.

Quality Issue

Design Principle: Trust and Reliability + Professional Communication

A broken link in the security section silently misleads enterprise users who follow security links as part of due diligence. The informal phrasing on line 403 creates tonal inconsistency in what is otherwise a well-polished reference document.

Proposed Improvement

Before (line 173):

See the [Security Architectur](/gh-aw/introduction/architecture/) for details.

After (line 173):

See the [Security Architecture](/gh-aw/introduction/architecture/) for details.

Before (line 403):

The easy way to fix this problem is to set a secret `GH_AW_CI_TRIGGER_TOKEN` with a Personal Access Token (PAT) with 'Contents: Read & Write' permission to your repo.

After (line 403):

To enable CI checks, add a repository secret named `GH_AW_CI_TRIGGER_TOKEN` containing a Personal Access Token (PAT) with **Contents: Read & Write** permission for the repository.

Why This Matters

• User Impact: Restores a working link in the security section; aligns tone with enterprise documentation standards
• Quality Factor: Trust (accurate links) + Professional Communication (consistent phrasing)
• Frequency: The FAQ is a high-traffic page; the CI trigger question is common among new users

Success Criteria

• Changes made to docs/src/content/docs/reference/faq.md only
• Link text reads "Security Architecture" (matches lines 217, 226)
• CI trigger answer uses direct, formal language
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/reference/faq.md

---

Task 2: Replace raw {status} token in failure message — .github/workflows/approach-validator.md

File to Modify: .github/workflows/approach-validator.md

Current Experience

Line 49: run-failure: "❌ [{workflow_name}]({run_url}) {status} during approach validation."

When a run times out, the posted comment reads: "❌ Approach Validator timed_out during approach validation." — a raw underscore-separated technical identifier embedded in natural language prose.

Quality Issue

Design Principle: Professional Communication — clear, human-readable status information

{status} renders the raw GitHub Actions conclusion value (failure, timed_out, cancelled). These are internal enum strings, not readable descriptions. The resulting sentence is grammatically awkward and looks like a template bug to readers unfamiliar with the workflow's message system.

Proposed Improvement

Before:

run-failure: "❌ [{workflow_name}]({run_url}) {status} during approach validation."

After:

run-failure: "❌ [{workflow_name}]({run_url}) did not complete approach validation. Check the [run log]({run_url}) for details."

Why This Matters

• User Impact: Reviewers get a clear, actionable message instead of a technical token; the inline link directly to the run log saves a navigation step
• Quality Factor: Professional Communication; Efficiency (fewer clicks to diagnose)
• Frequency: Every failed or timed-out approach-validator run posts this message to the triggering issue or PR

Success Criteria

• Changes made to .github/workflows/approach-validator.md only
• {status} interpolation removed from run-failure message
• Message is grammatically correct for all failure modes (timeout, error, cancellation)
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/approach-validator.md

---

References: §24888713799

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

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