UX Analysis Report – 2026-02-22: Quick Start heading hierarchy & workflow message tone

[github-actions[bot]]

Executive Summary

Today's targeted analysis covered:

• 1 documentation file: docs/src/content/docs/setup/quick-start.mdx
• 1 CLI command: gh aw audit
• 1 workflow message configuration: .github/workflows/archie.md
• 1 validation file: pkg/workflow/permissions_validation.go

Overall Quality: Mostly Professional — two focused improvements identified.

Key Finding: The Quick Start guide has a broken heading hierarchy that subtly undermines trust on the most critical user-facing page. A single heading level fix restores clarity and hierarchy.

---

Quality Highlights ✅

1. Audit Command Help Text — Comprehensive and Clear

• File: pkg/cli/audit.go
• What works well: Excellent URL format documentation — every supported URL variant is listed with a concrete example. Two-tier description (short + long) correctly separates scanning to summary vs. verbose details.
• Quote: "This command accepts:\n- A numeric run ID...\n- A GitHub Actions run URL..." — exhaustive and unambiguous.

2. Permissions Validation Error Messages — Actionable and Structured

• File: pkg/workflow/permissions_validation.go
• What works well: Error messages present the problem, map it to specific toolsets, and immediately offer two resolution paths (add permissions OR reduce toolsets). The documentation URL is appended automatically.
• Quote: "Option 1: Add missing permissions to your workflow frontmatter:" + "Option 2: Reduce the required toolsets in your workflow:" — model enterprise error-message pattern.

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Broken Heading Hierarchy in Quick Start — Single File Improvement

• File: docs/src/content/docs/setup/quick-start.mdx
• Current State: The four numbered steps use inconsistent heading levels. Steps 1, 2, and 4 use ### (h3), but Step 3 uses ## (h2):
  • Line 35: ### Step 1 - Install the extension (h3)
  • Line 56: ### Step 2 - Add the sample workflow and trigger a run (h3)
  • Line 75: ## Step 3 - Wait for the workflow to complete ← h2 — breaks hierarchy
  • Line 93: ### Step 4 - Customize your workflow (optional) (h3)
• Issue: Step 3 visually dominates the others in the rendered page due to the larger h2 heading, incorrectly implying it is a top-level section rather than a peer step. For new users — the most critical audience for a Quick Start guide — this creates subliminal confusion about workflow structure.
• User Impact: First-time users follow the Quick Start guide to evaluate the product. Broken visual hierarchy erodes the professional impression and may make the guide feel hurried or unpolished.
• Suggested Change: Change ## Step 3 - Wait for the workflow to complete → ### Step 3 - Wait for the workflow to complete
• Design Principle: Clarity and Precision — predictable, consistent structure signals care and quality.

Medium Priority

Opportunity 2: Overly Casual Persona Voice in Archie Workflow Messages — Single File Improvement

• File: .github/workflows/archie.md
• Current State (messages frontmatter):
  • run-started: "📐 Archie here! [{workflow_name}]({run_url}) is sketching the architecture on this {event_type}..."
  • run-success: "🎨 Blueprint complete! [{workflow_name}]({run_url}) has visualized the connections. The architecture speaks for itself! ✅"
  • run-failure: "📐 Drafting interrupted! [{workflow_name}]({run_url}) {status}. The diagram remains incomplete..."
• Issue: Messages use first-person persona announcement ("Archie here!") and casual boastful phrasing ("The architecture speaks for itself!"). The run-failure message also relies on {status} expansion which provides no actionable guidance.
• User Impact: Enterprise teams using slash-command workflows in issue trackers see these messages in their issue comments. An overly casual tone reduces confidence in automated tooling and is out of place in professional engineering discussion threads.
• Suggested Change: Remove the first-person announcement, maintain friendly tone but elevate professionalism, and add actionable context to the failure message.
• Design Principle: Professional Communication — business-appropriate tone that respects the engineer's context.

---

Files Reviewed

Category	File	Rating
Documentation	docs/src/content/docs/setup/quick-start.mdx	⚠️ Needs Minor Work
Documentation	docs/src/content/docs/reference/engines.md	✅ Professional
CLI Command	gh aw audit (pkg/cli/audit.go)	✅ Professional
Workflow Messages	.github/workflows/archie.md	⚠️ Needs Minor Work
Validation Code	pkg/workflow/permissions_validation.go	✅ Professional

Metrics

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

---

🎯 Actionable Tasks

Task 1: Fix Step 3 Heading Level in Quick Start Guide

File to Modify: docs/src/content/docs/setup/quick-start.mdx

Current Experience

Line 75 reads:

## Step 3 - Wait for the workflow to complete

while Steps 1, 2, and 4 all use ### (h3). In the rendered documentation, Step 3 appears as a prominent top-level section, visually separating it from the other steps and breaking the numbered flow.

Quality Issue

Design Principle: Clarity and Precision — consistent visual hierarchy is a foundational trust signal for enterprise documentation.

The broken level makes the Quick Start feel unpolished — this is the first page most evaluators visit, so inconsistency has outsized impact.

Proposed Improvement

Before (line 75):

## Step 3 - Wait for the workflow to complete

After:

### Step 3 - Wait for the workflow to complete

Why This Matters

• User Impact: New users following the numbered guide receive a consistent visual rhythm that guides them confidently through each step
• Quality Factor: Document hierarchy and structural clarity
• Frequency: Every new user visits the Quick Start guide — highest traffic documentation page

Success Criteria

• Change made to docs/src/content/docs/setup/quick-start.mdx only
• All four numbered steps use ### (h3) consistently
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/setup/quick-start.mdx
• One character change (## → ###) on line 75
• Can be completed in under 2 minutes

---

Task 2: Elevate Professional Tone in Archie Workflow Messages

File to Modify: .github/workflows/archie.md

Current Experience

Messages in the safe-outputs.messages frontmatter section use a first-person persona announcement and casual phrasing that appears in issue comments viewed by engineering teams:

run-started: "📐 Archie here! [{workflow_name}]({run_url}) is sketching the architecture on this {event_type}..."
run-success: "🎨 Blueprint complete! [{workflow_name}]({run_url}) has visualized the connections. The architecture speaks for itself! ✅"
run-failure: "📐 Drafting interrupted! [{workflow_name}]({run_url}) {status}. The diagram remains incomplete..."

Quality Issue

Design Principle: Professional Communication — automated messages in issue threads are read by engineers and managers and should reflect the reliability and quality of the tooling.

"Archie here!" mimics a chatbot greeting inappropriate for issue tracker context. "The architecture speaks for itself!" is casual boasting. The failure message relies on {status} without providing actionable context.

Proposed Improvement

Before:

run-started: "📐 Archie here! [{workflow_name}]({run_url}) is sketching the architecture on this {event_type}..."
run-success: "🎨 Blueprint complete! [{workflow_name}]({run_url}) has visualized the connections. The architecture speaks for itself! ✅"
run-failure: "📐 Drafting interrupted! [{workflow_name}]({run_url}) {status}. The diagram remains incomplete..."

After:

run-started: "📐 [{workflow_name}]({run_url}) is generating a Mermaid diagram for this {event_type}..."
run-success: "📊 Diagram generated by [{workflow_name}]({run_url}). ✅"
run-failure: "⚠️ [{workflow_name}]({run_url}) could not complete the diagram ({status}). Check the [run logs]({run_url}) for details."

Why This Matters

• User Impact: Engineers reading issue comments see concise, professional status messages without persona theatrics; failure messages now include a link to logs for debugging
• Quality Factor: Professional tone and actionable failure messaging
• Frequency: Triggered on every /archie slash command invocation

Success Criteria

• Changes made to .github/workflows/archie.md only
• First-person persona announcement removed from run-started
• Failure message includes reference to run logs for debugging
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: .github/workflows/archie.md
• Three message string replacements in the frontmatter messages: section
• No changes to workflow logic, prompt, or other frontmatter fields

---

References:

• §22276250055

AI generated by Delight

• expires on Mar 1, 2026, 11:32 AM UTC

[github-actions[bot]]

🤖 Beep boop! The smoke test agent was here!

Testing the Discussion Interaction step — just dropping by to say the automation is alive and well. Nothing to see here... unless you count this comment as proof that our workflows are working perfectly. 🎉

📰 BREAKING: Report filed by Smoke Copilot

[pelikhan]

/plan