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

[github-actions[bot]]

Executive Summary

Today's targeted analysis covered:

• 1 documentation file: docs/src/content/docs/reference/triggers.md
• 2 CLI command groups: validate, pr (short descriptions audit)
• 2 workflow message configurations: approach-validator.md, architecture-guardian.md
• 2 validation files: call_workflow_validation.go, template_validation.go

Overall Quality: ⚠️ Needs Minor Work

Key Finding: The approach-validator.md failure message exposes a raw {status} placeholder without actionable guidance, creating a confusing experience when the workflow fails. A companion pattern issue exists in architecture-guardian.md. The best-practice pattern is already established in archie.md.

---

Quality Highlights ✅

1. Exemplary Error Messages — call_workflow_validation.go

• File: pkg/workflow/call_workflow_validation.go
• What works well: Error messages include numbered fix steps, exact file paths, and explicit explanations of what was checked. The notFoundErr message is a model of clarity — it tells the user what was searched, where, and provides 3 concrete corrective actions.
• Quote: "Checked for: %s.md, %s.lock.yml, %s.yml\n\nTo fix:\n1. Verify the workflow file exists in .github/workflows/\n2. Ensure the filename matches exactly..."

2. Best-Practice Failure Message — archie.md

• File: .github/workflows/archie.md
• What works well: The run-failure message avoids the raw {status} placeholder and includes a direct log link:
  "📐 [{workflow_name}]({run_url}) encountered an issue and could not complete the architecture diagram. Check the [run logs]({run_url}) for details."
• This pattern is clear, professional, and actionable.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Vague Failure Message — approach-validator.md

• File: .github/workflows/approach-validator.md
• Current State (line 49): "❌ [{workflow_name}]({run_url}) {status} during approach validation."
• Issue: The {status} placeholder renders as a technical status string (e.g., "failed") without context. The message provides no actionable next step. Compare to archie.md which links to logs.
• User Impact: When a validation run fails, the developer sees a cryptic status token with no guidance on where to investigate or how to retry.
• Design Principle: Actionable Communication — error messages must point the user toward a resolution.
• Suggested Change:

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

Medium Priority

Opportunity 2: Generic Documentation Meta Description — triggers.md

• File: docs/src/content/docs/reference/triggers.md
• Current State (line 2): description: Triggers in GitHub Agentic Workflows
• Issue: This meta description is a near-duplicate of the page title. Compare to frontmatter.md which has: "Complete guide to all available frontmatter configuration options for GitHub Agentic Workflows, including triggers, permissions, AI engines, and workflow settings." — that description adds discoverability value. Additionally, the introductory paragraph (line 8) is terse and does not highlight the gh-aw-specific enhancements that differentiate this from standard GitHub Actions triggers.
• User Impact: Reduced discoverability via site search and search engines; new users don't understand at a glance what makes gh-aw triggers unique.
• Design Principle: Clarity and Precision — meta descriptions should set accurate expectations and aid navigation.
• Suggested Change (line 2):

description: Reference for all workflow trigger events in GitHub Agentic Workflows — including standard GitHub Actions triggers plus enhancements for reactions, cost control, skip conditions, and advanced filtering.

---

Files Reviewed

Documentation

• docs/src/content/docs/reference/triggers.md — Rating: ⚠️ Needs Minor Work (meta description)

CLI Commands

• gh aw validate — Rating: ✅ Professional
• gh aw pr — Rating: ⚠️ "Pull request utilities" is slightly vague but acceptable

Workflow Messages

• .github/workflows/approach-validator.md — Rating: ❌ Needs Significant Work (run-failure message)
• .github/workflows/archie.md — Rating: ✅ Professional (best-practice reference)

Validation Code

• pkg/workflow/call_workflow_validation.go — Rating: ✅ Professional
• pkg/workflow/template_validation.go — Rating: ✅ Professional

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Fix Failure Message — approach-validator.md

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

Current Experience

Line 49 contains:

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

The {status} token renders as a raw technical string. There is no link to logs or actionable guidance.

Quality Issue

Design Principle: Actionable Communication
When a workflow fails, users must know where to go next. The current message leaves them without direction.

Before:

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

After:

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

Why This Matters

• User Impact: Engineers receive actionable failure notifications instead of cryptic status tokens
• Quality Factor: Actionable error messages (matches the established pattern in archie.md)
• Frequency: Triggered on every workflow failure event

Success Criteria

• Single line change in .github/workflows/approach-validator.md only
• {status} placeholder removed
• Log link added via ({run_url})
• Quality rating improves from ❌ to ✅

Scope Constraint

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

---

Task 2: Improve Meta Description — triggers.md

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

Current Experience

Line 2:

description: Triggers in GitHub Agentic Workflows

This repeats the title verbatim and adds no additional discoverability or context.

Quality Issue

Design Principle: Clarity and Precision
Meta descriptions in Astro Starlight populate both <meta name="description"> and the search index summary. A generic description fails to differentiate this page from a title alone.

Before:

description: Triggers in GitHub Agentic Workflows

After:

description: Reference for all workflow trigger events in GitHub Agentic Workflows — including standard GitHub Actions triggers plus enhancements for reactions, cost control, skip conditions, and advanced filtering.

Why This Matters

• User Impact: Improved search result clarity and site search relevance
• Quality Factor: Technical accuracy and documentation completeness
• Frequency: Every user navigating trigger documentation via search

Success Criteria

• Single line change in docs/src/content/docs/reference/triggers.md only
• Description exceeds 80 characters and summarizes the unique gh-aw features
• Quality rating improves from ⚠️ to ✅

Scope Constraint

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

---

References: §24956162884

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

• expires on Apr 29, 2026, 12:08 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #28715.