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

[github-actions[bot]]

Executive Summary

Today's analysis covered:

• 1 documentation file: docs/src/content/docs/troubleshooting/errors.md
• 1 CLI validation file: pkg/workflow/engine_validation.go
• 2 workflow message configs: breaking-change-checker.md, security-review.md

Overall Quality: Mostly Professional ⚠️

Key Finding: The errors.md troubleshooting page has a misleading section title ("Top User-Facing Errors") that undermines the document's professional organization, and breaking-change-checker.md uses an informal, consumer-app tone in its status messages.

---

Quality Highlights ✅

Highlight 1: errors.md — Lifecycle-based error organization

• File: docs/src/content/docs/troubleshooting/errors.md
• What works well: Clear lifecycle hierarchy (Schema Validation → Compilation → Runtime → Engine-Specific → File Processing → Safe Output). Each entry follows a consistent three-part pattern: error code in backticks → plain-language explanation → corrected code example. The Typo Detection callout (lines 14–16) using a GitHub-flavored [!TIP] alert is especially effective — it proactively reduces support friction by pointing users to fuzzy-match suggestions.

Highlight 2: security-review.md messages — Professional, consistent voice

• File: .github/workflows/security-review.md
• What works well: run-started, run-success, and run-failure messages all use declarative past/present tense without exclamation marks. Emoji are minimal and purposeful: 🔍 (scanning), 🔒 (secured), ⚠️ (warning). This is a strong reference pattern for other workflows.

Highlight 3: engine_validation.go — Actionable error messages

• File: pkg/workflow/engine_validation.go
• What works well: Every error message includes a concrete YAML fix example and a documentation URL (constants.DocsEnginesURL). The validateEngineAuthDefinition function covers all three auth strategies with strategy-specific guidance, preventing user guesswork. The "Did you mean" suggestion for unknown runtime.id values mirrors the fuzzy-match pattern from schema validation.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Rename misleading section in errors.md

• File: docs/src/content/docs/troubleshooting/errors.md
• Current State (line 215–217):

  ## Top User-Facing Errors
  
  This section documents the most common errors you may encounter when working with GitHub Agentic Workflows.
  

• Issue: "Top User-Facing Errors" implies a frequency ranking — these are supposedly the errors users encounter most. But every other section in the document also contains user-facing errors. The heading creates a false premise and makes the page harder to scan: an enterprise user looking for a strict-mode error will look in "Strict Mode" not "Top User-Facing Errors," and may miss the relevant content.
• User Impact: Increases time-to-resolution for the 12 errors documented in this section, which include high-frequency configuration errors (strict mode network, write permissions, MCP configuration). Users scanning by category won't find these errors in the expected place.
• Suggested Change: Rename to ## Strict Mode and Configuration Errors and update the intro sentence to explain what this group of errors has in common.
• Design Principle: Clarity and Precision — section headings must accurately predict content.

Medium Priority

Opportunity 2: Professional tone in breaking-change-checker.md status messages

• File: .github/workflows/breaking-change-checker.md
• Current State (lines 32–34):

  run-started: "🔬 Breaking Change Checker online! [{workflow_name}]({run_url}) is analyzing API compatibility on this {event_type}..."
  run-success: "✅ Analysis complete! [{workflow_name}]({run_url}) has reviewed all changes. Compatibility verdict delivered! 📋"
  run-failure: "🔬 Analysis interrupted! [{workflow_name}]({run_url}) {status}. Compatibility status unknown..."

• Issue: Three problems compound to create an informal consumer-app tone:
  1. "Breaking Change Checker online!" — "online!" is a casual announcement phrase, inconsistent with professional tooling
  2. "Compatibility verdict delivered! 📋" — appended sentence with two exclamation marks and a clipboard emoji turns a neutral success event into a celebration
  3. Failure message uses 🔬 (microscope/analysis emoji) instead of a warning indicator, sending the wrong semantic signal
• Reference: Compare with security-review.md which uses "🔒 [{workflow_name}]({run_url}) completed the security review." — clean, declarative, no exclamation marks.
• User Impact: In enterprise pull request reviews, status messages appear in PR timelines visible to stakeholders. Overly casual messages reduce perceived tool professionalism.
• Suggested Change: Align with the security-review.md pattern.
• Design Principle: Professional Communication — appropriate tone for enterprise context.

---

Files Reviewed

Documentation

• docs/src/content/docs/troubleshooting/errors.md — Rating: ⚠️ Needs Minor Work (misleading section name)

CLI / Validation Code

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

Workflow Messages

• .github/workflows/breaking-change-checker.md — Rating: ⚠️ Needs Minor Work (informal tone)
• .github/workflows/security-review.md — Rating: ✅ Professional

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Rename misleading section — errors.md

File to Modify: docs/src/content/docs/troubleshooting/errors.md

Current Experience

Line 215 contains the heading ## Top User-Facing Errors followed by the description: "This section documents the most common errors you may encounter when working with GitHub Agentic Workflows."

This section contains 12 errors spanning strict mode rules, MCP configuration, permission checks, toolset settings, and the public-repository-requires-strict-mode error. None of these fit cleanly into the lifecycle-based categories above (Schema/Compilation/Runtime/Engine/File/Safe Output).

Quality Issue

Design Principle: Clarity and Precision

"Top User-Facing Errors" creates a false hierarchy — every error documented in this file is user-facing. Enterprise users scanning the page via Ctrl+F or the sidebar will look for "Strict Mode" or "MCP" before they look for "Top". This mismatch slows time-to-resolution.

Proposed Improvement

Before (line 215–217):

## Top User-Facing Errors

This section documents the most common errors you may encounter when working with GitHub Agentic Workflows.

After:

## Strict Mode and Configuration Errors

These errors occur when workflow configuration options conflict with security policies or platform requirements, such as strict mode constraints, MCP server settings, and GitHub repository feature requirements.

Why This Matters

• User Impact: The 12 errors in this section cover high-frequency configuration scenarios (strict mode, MCP type resolution, toolset setup). Accurate naming allows users to find these errors faster.
• Quality Factor: Predictable information architecture — section names should tell users what to expect.
• Frequency: These errors appear during initial workflow setup and after strict-mode upgrades, affecting new and experienced users alike.

Success Criteria

• Changes made to docs/src/content/docs/troubleshooting/errors.md only
• Section heading accurately reflects the 12 errors it contains
• Intro sentence distinguishes this section from lifecycle-based sections above
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/troubleshooting/errors.md
• No changes to sidebar config, other docs, or source code required
• Can be completed independently

---

Task 2: Align breaking-change-checker.md messages with professional tone

File to Modify: .github/workflows/breaking-change-checker.md

Current Experience

Lines 32–34 define the three user-visible status messages. These messages appear in PR comment timelines and issue threads visible to all team members and stakeholders.

Quality Issue

Design Principle: Professional Communication

Compared to security-review.md (the reference standard in this repo), the breaking-change-checker messages:

• Use exclamation marks where declarative statements suffice
• Append secondary celebratory sentences ("Compatibility verdict delivered! 📋")
• Choose emoji that signal intent (analysis) rather than status (warning) on the failure case

Proposed Improvement

Before (lines 32–34):

run-started: "🔬 Breaking Change Checker online! [{workflow_name}]({run_url}) is analyzing API compatibility on this {event_type}..."
run-success: "✅ Analysis complete! [{workflow_name}]({run_url}) has reviewed all changes. Compatibility verdict delivered! 📋"
run-failure: "🔬 Analysis interrupted! [{workflow_name}]({run_url}) {status}. Compatibility status unknown..."

After:

run-started: "🔬 [{workflow_name}]({run_url}) is analyzing API compatibility on this {event_type}..."
run-success: "✅ [{workflow_name}]({run_url}) completed the API compatibility analysis."
run-failure: "⚠️ [{workflow_name}]({run_url}) {status} during API compatibility analysis."

Why This Matters

• User Impact: Stakeholders reading PR timelines see cleaner, more professional status messages that are consistent with other workflow messages in the repository.
• Quality Factor: Consistent voice across all workflow messages reduces cognitive overhead.
• Frequency: This workflow runs on every PR that could affect API compatibility — high-frequency visibility.

Success Criteria

• Changes made to .github/workflows/breaking-change-checker.md only
• No exclamation marks in status messages (matched security-review.md pattern)
• Failure message uses ⚠️ instead of 🔬
• Message structure: [emoji] [{workflow_name}]({run_url}) [verb phrase]
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/breaking-change-checker.md
• No changes to lock file, other workflows, or documentation required
• Can be completed independently

---

References: §24453614364

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

• expires on Apr 18, 2026, 12:15 PM UTC