UX Analysis Report – 2026-02-21: Engines Docs Typos & Logs Command Scannability

[github-actions[bot]]

Today's targeted analysis reviewed 5 files across documentation, CLI, workflow messages, and validation code. Overall quality is professional, with two actionable improvements identified.

Files Reviewed

File	Category	Rating
docs/src/content/docs/reference/engines.md	Documentation	⚠️ Needs Minor Work
docs/src/content/docs/troubleshooting/common-issues.md	Documentation	✅ Professional
pkg/cli/logs_command.go	CLI Command	⚠️ Needs Minor Work
.github/workflows/archie.md + brave.md	Workflow Messages	✅ Professional
pkg/workflow/engine_validation.go	Validation Errors	✅ Professional

Quality Highlights ✅

1. Troubleshooting Documentation

• File: docs/src/content/docs/troubleshooting/common-issues.md
• What works well: Clear section hierarchy, each issue has Cause + Solution + Code Example pattern, actionable callout blocks ([!TIP], [!NOTE])
• Quote: The Playwright error section (lines 155–188) is an excellent model — exact error text, clear cause, before/after code showing correct vs. incorrect usage

2. Engine Validation Error Messages

• File: pkg/workflow/engine_validation.go
• What works well: Errors include valid option list, "did you mean" fuzzy suggestion, inline YAML example, and documentation URL — all in one message
• Quote: "invalid engine: %s. Valid engines are: %s.\n\nDid you mean: %s?\n\nExample:\nengine: copilot\n\nSee: %s" — exactly what a developer needs to fix the issue immediately

---

Improvement Opportunities 💡

High Priority

Opportunity 1: Typos in AI Engines Reference — docs/src/content/docs/reference/engines.md

• File: docs/src/content/docs/reference/engines.md
• Current State:
  • Line 22: "You can optionally request the use of of the Copilot CLI" — duplicate "of"
  • Line 106: "See Copilot Agent Filess" — extra 's' in "Files"
• Issue: Typos in documentation erode trust. This page is a primary reference for new users setting up their AI engine, and is likely one of the most-visited pages in the docs.
• User Impact: Enterprise users evaluating the tool notice typos. It signals lower documentation quality and reduces confidence in the accuracy of the content.
• Design Principle: Trust and Reliability — accurate, polished content builds confidence in the product

Medium Priority

Opportunity 2: Logs Command Help Text Lacks Scannable Structure — pkg/cli/logs_command.go

• File: pkg/cli/logs_command.go
• Current State (lines 51–79): 25 usage examples listed sequentially with no grouping. Users must read all 25 to find the example relevant to their task.
• Issue: The examples section is a wall of similar-looking lines. Finding a date-filter example vs. a filter-by-engine example requires reading through all of them.
• User Impact: CLI power users rely on --help as their primary reference. When examples aren't grouped, discovery time increases and users may miss useful flags entirely.
• Suggested Change: Group examples into 4–5 labeled sections using inline # comments:
  • # Basic usage, # Date filtering, # Content filtering, # Output options, # Advanced
• Design Principle: Efficiency and Productivity — direct path to outcome without reading irrelevant content

---

View Workflow Messages Analysis

archie.md and brave.md messages use a consistent persona voice with status-appropriate emojis (📐 for started, 🎨 for success, interruption framing for failure). The tone is intentionally chatbot-like for a slash-command assistant context, which is appropriate. The pattern is consistent across both workflows, showing good systemic coherence.

One note: run-started messages use first-person bot names ("Archie here!") which adds personality but could feel inconsistent if other workflows don't follow the same pattern. This is a minor style consideration, not a blocking issue.

---

🎯 Actionable Tasks

Here are 2 targeted improvement tasks, each affecting a single file:

---

Task 1: Fix Typos in AI Engines Reference

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

Current Experience

Line 22:

You can optionally request the use of of the Copilot CLI in your workflow frontmatter:
```

Line 106:
```
See [Copilot Agent Filess](/gh-aw/reference/copilot-custom-agents/) for details
```

**Quality Issue**

**Design Principle**: Trust and Reliability

Two typos on a high-traffic reference page reduce professional credibility. Enterprise users comparing tools actively notice documentation quality as a proxy for product quality.

**Proposed Improvement**

**Before (line 22):**
```
You can optionally request the use of of the Copilot CLI in your workflow frontmatter:
```

**After (line 22):**
```
You can optionally request the use of the Copilot CLI in your workflow frontmatter:
```

**Before (line 106):**
```
See [Copilot Agent Filess](/gh-aw/reference/copilot-custom-agents/) for details on creating and configuring custom agents.
```

**After (line 106):**
```
See [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details on creating and configuring custom agents.

Why This Matters

• User Impact: Polished documentation signals product quality — typos reduce perceived reliability
• Quality Factor: Precision and accuracy
• Frequency: This page is linked from the main Frontmatter reference and is a first-visit page for new users

Success Criteria

• Changes made to docs/src/content/docs/reference/engines.md only
• Both typos corrected (line 22 "of of" → "of", line 106 "Filess" → "Files")
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: docs/src/content/docs/reference/engines.md
• No changes to other files required

---

Task 2: Add Example Groupings to Logs Command Help Text

File to Modify: pkg/cli/logs_command.go

Current Experience

The Long description contains 25 examples (lines 51–79) listed sequentially with no visual separation or categorization. Users running gh aw logs --help see a flat list and must scan all entries to find a relevant example.

Quality Issue

Design Principle: Efficiency and Productivity

Without grouping, users can't jump to the section relevant to their task. The examples currently mix date filtering, content filtering, output format, and advanced range filtering without separation.

Proposed Improvement

Add comment-style group headers within the examples block in the Long string:

Before:

Examples:
  gh aw logs                           # Download logs for all workflows
  gh aw logs weekly-research           # Download logs for specific workflow
  gh aw logs weekly-research.md        # Download logs (alternative format)
  gh aw logs -c 10                     # Download last 10 matching runs
  gh aw logs --start-date 2024-01-01   # Download all runs after date
  ... (22 more lines)

After:

Examples:
  # Basic usage
  gh aw logs                           # Download logs for all workflows
  gh aw logs weekly-research           # Download logs for specific workflow
  gh aw logs -c 10                     # Download last 10 matching runs

  # Date filtering
  gh aw logs --start-date 2024-01-01   # Download all runs after date
  gh aw logs --end-date 2024-01-31     # Download all runs before date
  gh aw logs --start-date -1w          # Download runs from last week
  gh aw logs --start-date -1mo         # Download runs from last month

  # Content filtering
  gh aw logs --engine claude           # Filter by engine
  gh aw logs --firewall                # Filter runs with firewall enabled
  gh aw logs --safe-output missing-tool  # Filter by safe output type
  gh aw logs --ref main                # Filter by branch

  # Run ID range filtering
  gh aw logs --after-run-id 1000       # Filter runs after run ID 1000
  gh aw logs --before-run-id 2000      # Filter runs before run ID 2000

  # Output options
  gh aw logs --json                    # Output metrics in JSON format
  gh aw logs --parse                   # Generate Markdown reports
  gh aw logs --tool-graph              # Generate Mermaid tool sequence graph
  gh aw logs -o ./my-logs              # Custom output directory

  # Cross-repository
  gh aw logs weekly-research --repo owner/repo  # Download from specific repository

Why This Matters

• User Impact: Users find their relevant example in 2–3 seconds instead of scanning 25+ lines
• Quality Factor: Efficiency and cognitive load reduction
• Frequency: Every user of gh aw logs --help encounters this; it's a primary discovery mechanism for advanced flags

Success Criteria

• Changes made to pkg/cli/logs_command.go only
• Examples grouped into logical sections with comment headers
• All existing examples preserved (none removed)
• Quality rating improves from ⚠️ to ✅

Scope Constraint

• Single file only: pkg/cli/logs_command.go
• Only the Long string's examples section is modified

---

References:

• §22256008185

AI generated by Delight

• expires on Feb 28, 2026, 11:32 AM UTC

[pelikhan]

/plan

[pelikhan]

/plan