[delight] UX Analysis 2026-05-31: Safe-Outputs Progressive Disclosure & Secrets Error Clarity

[github-actions[bot]]

User Experience Analysis — 2026-05-31

Executive Summary

Analyzed 5 files: 2 documentation, 2 workflow message configs, 1 validation file.

Overall Quality: Professional with 2 minor improvements identified.

Key Finding: safe-outputs.md lists 34 output types in a single flat always-expanded catalog — wrapping the 4 lower-frequency categories in <details> blocks would reduce first-read cognitive load by ~45%.

---

Quality Highlights ✅

dependabot-rollout.md — Clear Mermaid flow diagram, realistic secrets-permissions table, actionable Best Practices section. Quote: "Keep max: 5 on the orchestrator during initial rollout; increase once you've validated the worker output" — enterprise-appropriate, specific guidance.

brave.md workflow messages — Concise, consistent status progression (searching → complete → failed), sparse and meaningful emoji use, no theatrical prose.

---

Improvement Opportunities 💡

High Priority — docs/src/content/docs/reference/safe-outputs.md

Lines 23–90 list 34 output types across 7 categories, all expanded at page load. The 4 lower-frequency categories (Projects/Releases/Assets, Security & Agent Tasks, Custom Safe Output Jobs, GitHub Action Wrappers) account for 15+ bullets that most users navigating to create-issue or add-comment never need on first read.

Proposed: Wrap the 4 lower-frequency categories in <details><summary> blocks. Keep Issues & Discussions, Pull Requests, and Labels/Assignments fully visible.

Design Principle: Progressive Disclosure — critical information immediately visible; advanced options opt-in.

Medium Priority — pkg/workflow/secrets_validation.go

Line 22: "invalid secrets expression: must be a GitHub Actions expression with secrets reference (e.g., ...)"

"Secrets" appears three times in the lead clause; "secrets expression" and "secrets reference" are near-synonyms creating circular phrasing.

Proposed: "invalid value: must use a GitHub Actions secrets expression (e.g., '${{ secrets.MY_SECRET }}' or '${{ secrets.SECRET1 || secrets.SECRET2 }}')"

Design Principle: Clarity and Precision — remove redundancy so users parse the fix faster.

---

Files Reviewed

File	Rating
docs/src/content/docs/examples/multi-repo/dependabot-rollout.md	✅ Professional
docs/src/content/docs/reference/safe-outputs.md	⚠️ Needs Minor Work
.github/workflows/smoke-service-ports.md	✅ Professional
.github/workflows/brave.md	✅ Professional
pkg/workflow/secrets_validation.go	⚠️ Needs Minor Work

Quality Distribution: ✅ Professional: 3 · ⚠️ Needs Minor Work: 2 · ❌ Needs Significant Work: 0

---

🎯 Actionable Tasks

Task 1: Progressive Disclosure in Safe Outputs Type Catalog

File: docs/src/content/docs/reference/safe-outputs.md

Wrap the 4 lower-frequency categories (lines 59–90) in <details> blocks:

<details>
<summary><strong>Projects, Releases & Assets</strong></summary>

- [**Create Project**](...) - ...
- [**Update Project**](...) - ...
...

</details>

<details>
<summary><strong>Security & Agent Tasks</strong></summary>

- [**Dispatch Workflow**](...) - ...
...

</details>

<details>
<summary><strong>Custom Safe Output Jobs (<code>jobs:</code>)</strong></summary>

Create custom post-processing jobs...

</details>

<details>
<summary><strong>GitHub Action Wrappers (<code>actions:</code>)</strong></summary>

Mount any public GitHub Action...

</details>

Keep Issues & Discussions, Pull Requests, and Labels/Assignments & Reviews fully visible. Preserve all existing anchor links.

Success criteria: 4 categories collapsed; 3 high-traffic categories remain visible; no link breakage.

---

Task 2: Reduce Redundancy in Secrets Validation Error

File: pkg/workflow/secrets_validation.go

Before (line 22):

errors.New("invalid secrets expression: must be a GitHub Actions expression with secrets reference (e.g., '${{ secrets.MY_SECRET }}' or '${{ secrets.SECRET1 || secrets.SECRET2 }}')")

After:

errors.New("invalid value: must use a GitHub Actions secrets expression (e.g., '${{ secrets.MY_SECRET }}' or '${{ secrets.SECRET1 || secrets.SECRET2 }}')")

Note: test assertions in jobs_secrets_validation_test.go match on "does not match pattern" (substring) — not affected by this change.

Success criteria: Single "secrets" reference in lead clause; examples unchanged; tests pass.

---

References: §26716170811

📊 User experience analysis by Delight · sonnet46 4.8M · ◷

• expires on Jun 3, 2026, 3:16 PM UTC