[delight] UX Analysis Report — 2026-06-24: Architecture Guardian Status Messages

[github-actions[bot]]

User Experience Analysis Report — 2026-06-24

Executive Summary

Today's analysis focused on:

• 2 documentation files
• 2 workflow message configurations
• 1 validation file

Overall Quality: Mixed — documentation and validation code are professional; workflow status messages have friction points.

Key Finding: architecture-guardian.md has theatrical, imprecise status messages across all three states (started, success, failure), reducing professional credibility in enterprise monitoring contexts.

---

Quality Highlights ✅

Example 1: Sharing Workflows Documentation

• File: docs/src/content/docs/practices/sharing-workflows.md
• What works well: Seven clearly numbered sharing layers, each with practical code examples and explicit cross-references. The versioning section precisely distinguishes exact tags, moving refs, branch refs, and SHA pins — eliminating a common source of user confusion.
• Quote/Reference: "Exact release tags (@v1.2.0) pin to a specific immutable release. They do not move on their own, so gh aw update will keep fetching that same tagged version unless you change the source: ref explicitly."

Example 2: Strict Mode Sandbox Validation Errors

• File: pkg/workflow/strict_mode_sandbox_validation.go
• What works well: A single parameterized error template names the exact forbidden field path, offers two specific remediation options, and links directly to reference documentation — all in one sentence.
• Quote/Reference: "strict mode: '%s' is not allowed because it is an internal implementation detail. Remove '%s' or set 'strict: false' to disable strict mode. See: (redacted)"

---

Improvement Opportunities 💡

High Priority: Theatrical and Imprecise Status Messages — architecture-guardian.md

• File: .github/workflows/architecture-guardian.md
• Current State (lines 55–57):

  run-started: "🏛️ Architecture Guardian online! [{workflow_name}]({run_url}) is scanning code structure on this {event_type}..."
  run-success: "✅ Architecture scan complete! [{workflow_name}]({run_url}) has reviewed code structure. Report delivered! 📋"
  run-failure: "🏛️ Architecture scan failed! [{workflow_name}]({run_url}) {status}. Structure status unknown..."

• Issues:
  1. run-started — "Guardian online!" is theatrical launch-announcement phrasing. The trailing ... implies ongoing uncertainty on a message that signals a confirmed start.
  2. run-success — "Report delivered! 📋" is redundant (a completed scan implies delivery); the 📋 emoji is purely decorative; two exclamation marks in one message.
  3. run-failure — reuses the 🏛️ emoji from the success and started messages, making rapid visual triage harder in monitoring dashboards. "Structure status unknown..." is imprecise: a failed workflow means the scan did not complete, not that the structural status is unknowable.
• User Impact: Monitoring dashboards and notification channels consume these messages verbatim. Ambiguous and theatrical phrasing slows triage and reduces confidence in the tool.
• Suggested Change:

  run-started: "🏛️ Architecture Guardian scanning code structure on `{event_type}`. [{workflow_name}]({run_url})"
  run-success: "✅ Architecture scan complete. [{workflow_name}]({run_url}) reviewed code structure and delivered a report."
  run-failure: "❌ Architecture scan failed. [{workflow_name}]({run_url}) {status}. Scan did not complete."

• Design Principle: Professional Communication; Trust and Reliability

Medium Priority: run-failure message — discussion-task-miner.md (recurring finding)

• File: .github/workflows/discussion-task-miner.md
• Issue: run-failure uses "interrupted!" (inaccurate — implies external cancellation rather than a runtime error) and "Please review the logs..." (too casual; trailing ... is indecisive).
• Status: A pending improvement task was created on 2026-06-23. No new issue created this run to avoid duplication.

---

Files Reviewed

Documentation

• docs/src/content/docs/practices/sharing-workflows.md — ✅ Professional
• docs/src/content/docs/specs/ai-credits-specification.md — ✅ Professional

Workflow Messages

• .github/workflows/architecture-guardian.md — ⚠️ Needs Minor Work
• .github/workflows/discussion-task-miner.md — ⚠️ Needs Minor Work (recurring; pending task open)

Validation Code

• pkg/workflow/strict_mode_sandbox_validation.go — ✅ Professional

---

Metrics

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

---

🎯 Actionable Tasks

Task 1: Fix Status Messages — .github/workflows/architecture-guardian.md

File to Modify: .github/workflows/architecture-guardian.md

Current Experience

Lines 55–57 of the safe-outputs.messages block:

run-started: "🏛️ Architecture Guardian online! [{workflow_name}]({run_url}) is scanning code structure on this {event_type}..."
run-success: "✅ Architecture scan complete! [{workflow_name}]({run_url}) has reviewed code structure. Report delivered! 📋"
run-failure: "🏛️ Architecture scan failed! [{workflow_name}]({run_url}) {status}. Structure status unknown..."

Quality Issue

Design Principle: Professional Communication; Trust and Reliability

Three specific problems across all three message states:

1. run-started: "Guardian online!" is a theatrical system-announcement phrase. The trailing ... implies hesitation on a message that signals a confirmed, active scan.
2. run-success: "Report delivered! 📋" restates what "scan complete" already implies, adds a second exclamation mark, and appends a clipboard emoji that carries no information.
3. run-failure: The 🏛️ emoji is also used in run-started, making it appear as a neutral/positive indicator. Reusing it on failure creates visual ambiguity. "Structure status unknown..." mischaracterizes the failure — a workflow failure means the scan did not complete, not that structural status is indeterminate.

Proposed Improvement

Before:

run-started: "🏛️ Architecture Guardian online! [{workflow_name}]({run_url}) is scanning code structure on this {event_type}..."
run-success: "✅ Architecture scan complete! [{workflow_name}]({run_url}) has reviewed code structure. Report delivered! 📋"
run-failure: "🏛️ Architecture scan failed! [{workflow_name}]({run_url}) {status}. Structure status unknown..."

After:

run-started: "🏛️ Architecture Guardian scanning code structure on `{event_type}`. [{workflow_name}]({run_url})"
run-success: "✅ Architecture scan complete. [{workflow_name}]({run_url}) reviewed code structure and delivered a report."
run-failure: "❌ Architecture scan failed. [{workflow_name}]({run_url}) {status}. Scan did not complete."

Why This Matters

• User Impact: Monitoring dashboards and Slack/Teams notification channels display these messages as brief status lines. Consistent, scannable phrasing reduces triage time.
• Quality Factor: Removes theatrical phrasing while preserving all informational content; distinguishes failure visually from success/started states.
• Frequency: Every workflow run generates exactly one of these three messages.

Success Criteria

• Changes made to .github/workflows/architecture-guardian.md only
• run-failure uses a distinct emoji (❌) that visually separates it from other states
• All three messages use declarative sentences without unnecessary exclamation marks or trailing ...
• run-failure states that the scan did not complete rather than expressing uncertainty about structural state
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/architecture-guardian.md
• No changes to other files required
• Can be completed independently

📊 User experience analysis by Delight · 69.5 AIC · ⌖ 10.5 AIC · ⊞ 8.4K · ◷

• expires on Jun 27, 2026, 7:39 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Delight.

A newer discussion is available at Discussion #41483.