[delight] UX Analysis Report — 2026-07-11

[github-actions[bot]]

User Experience Analysis Report — 2026-07-11

Executive Summary

Today's analysis focused on:

• 2 documentation files
• 1 CLI command (gh aw audit)
• 2 workflow message configurations
• 1 validation file

Overall Quality: Needs Minor Work

Key Finding: docs/src/content/docs/patterns/issue-ops.md is significantly thinner than peer pattern pages — missing a decision table and Sub-Issues semantics — creating friction for a high-traffic automation pattern.

Quality Highlights

Highlight 1: BatchOps Decision Table

• File: docs/src/content/docs/patterns/batch-ops.md
• What works well: The strategy-selection table gives users a fast, unambiguous answer to "which approach should I use?" — a model for all pattern pages.
• Quote: | 50–500 items, order doesn't matter | BatchOps with chunked processing |

Highlight 2: Dispatch Workflow Validation Error Messages

• File: pkg/workflow/dispatch_workflow_validation.go
• What works well: Every error explains why the constraint exists and provides a numbered fix. The self-reference error names the workflow, explains infinite-loop risk, and offers two alternatives.

Files Reviewed & Metrics

Documentation

• docs/src/content/docs/patterns/batch-ops.md — Rating: Professional
• docs/src/content/docs/patterns/issue-ops.md — Rating: Needs Significant Work

CLI Commands

• gh aw audit (pkg/cli/audit.go) — Rating: Needs Minor Work

Workflow Messages

• .github/workflows/outcome-collector.md — Rating: Professional
• .github/workflows/smoke-workflow-call.md — Rating: Professional

Validation Code

• pkg/workflow/dispatch_workflow_validation.go — Rating: Professional

Metrics

• Files Analyzed: 6
• Quality Distribution: Professional: 4 | Needs Minor Work: 1 | Needs Significant Work: 1

---

Actionable Tasks

Task 1: Expand IssueOps Documentation

File to Modify: docs/src/content/docs/patterns/issue-ops.md

Current Experience

The page has a brief prose intro, one triage example, and a Sub-Issues section that drops code mid-paragraph without explaining the temporary_id field, the parent field syntax, or what link-sub-issue does differently. Compared to batch-ops.md (decision table, 4 strategies, mermaid diagrams), issue-ops.md leaves users without context to choose or configure the pattern correctly.

Design Principle: Efficiency and Productivity

Proposed Improvement

Add:

1. A trigger-type decision table comparing issues: opened, command, and label triggers.
2. An inline explanation of temporary_id semantics before the Sub-Issues code block.
3. A mermaid diagram for the triage flow.

Before (Sub-Issues section):

## Organizing Work with Sub-Issues

Break large work into agent-ready tasks using parent-child issue hierarchies. Create hierarchies with the `parent` field and temporary IDs, or link existing issues with `link-sub-issue`:

After:

## Organizing Work with Sub-Issues

Break large work into agent-ready tasks using parent-child issue hierarchies.

**Temporary IDs** (`temporary_id`) let you cross-reference issues before they exist. Use the format `aw_<alphanumeric>` (e.g., `aw_abc123`). The runtime replaces each temporary ID with the real issue number after creation. Use the `parent` field to attach a sub-issue to its parent by temporary ID, or use `link-sub-issue` to attach an existing issue.

Why This Matters

• User Impact: Reduces time-to-working-workflow for issue hierarchy patterns from trial-and-error to a clear guided path.
• Frequency: IssueOps is a high-traffic entry point; many users encounter Sub-Issues before reading the safe-outputs reference.

Success Criteria

• Changes made to docs/src/content/docs/patterns/issue-ops.md only
• temporary_id semantics explained inline before the code block
• A trigger-type decision table is present
• Quality rating improves from Needs Significant Work to Professional

Scope Constraint: Single file only — docs/src/content/docs/patterns/issue-ops.md

---

Task 2: Add Multi-Run Diff Example to Audit CLI

File to Modify: pkg/cli/audit.go

Current Experience

auditCommandLong describes single-run and multi-run diff modes, but auditCommandExample lists 6 URL format variants without a single multi-run diff example — the most non-obvious capability. Additionally, the long description does not tell users where output files are written.

Design Principle: Efficiency and Productivity — examples should cover all major modes, not just input-format variations.

Before (auditCommandExample, last line):

  gh aw audit (github.example.com/redacted)  # Audit from GitHub Enterprise

After (append two lines):

  gh aw audit (github.example.com/redacted)  # Audit from GitHub Enterprise
  gh aw audit 1111111111 2222222222 3333333333   # Compare runs: first is base, rest are compared against it
  gh aw audit --stdin < run-ids.txt              # Read run IDs from a file (one per line)

Also append to auditCommandLong:

Output files are written to the directory specified by --output (default: ./logs).

Why This Matters

• User Impact: Multi-run diff is the distinguishing capability of gh aw audit; without an example, users must guess the syntax.
• Frequency: Used by CI pipelines and engineers investigating regressions.

Success Criteria

• Changes made to pkg/cli/audit.go only
• auditCommandExample includes at least one multi-run diff invocation
• auditCommandLong states where output is written
• Quality rating improves from Needs Minor Work to Professional

Scope Constraint: Single file only — pkg/cli/audit.go

📊 User experience analysis by Delight · 63.1 AIC · ⌖ 7.65 AIC · ⊞ 8.4K · ◷

• expires on Jul 14, 2026, 7:06 AM UTC-08:00