Repository navigation
Description
Description
The frontmatter reference documentation (docs/src/content/docs/reference/frontmatter.md) is comprehensive but presents high information density that creates cognitive overload for users. New users face a wall of 25+ configuration options when they likely need only 3-5 fields to start.
Current State
Lines 23-27 list all configuration options in a single dense paragraph:
The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `safe-inputs`, `safe-outputs`, `network`, `tools`).User Impact
- New users: Face 10+ minutes reading entire reference when they need only 3-5 core fields
- Expert users: Must scroll through extensive documentation to find advanced features
- Lack of visual hierarchy: No progressive disclosure makes quick reference difficult
Suggested Changes
Add a "Quick Reference" section at the top with the 5 most common fields, then organize remaining content using collapsible <details> sections:
Add at the top (before current line 23):
## Quick Reference
For most workflows, you only need these 5 fields:
```yaml
on: workflow_dispatch # When to run
permissions: contents:read # What it can access
engine: copilot # Which AI to use
tools: # Available tools
edit:View All Configuration Options
[Move current comprehensive documentation here]
Organize remaining content into collapsible sections by topic:
- Core Workflow Settings (expand for details)
- Advanced Settings (expand for details)
- GitHub Actions Integration (expand for details)
Files Affected
docs/src/content/docs/reference/frontmatter.md(single file only)
Success Criteria
- Quick reference section added with 5 core fields
- At least 3 major sections wrapped in
<details>tags - Essential information remains visible
- Comprehensive details available but collapsed by default
- Time-to-comprehension reduced from 10+ minutes to 2-3 minutes
Design Principle
Efficiency and Productivity - "Minimize cognitive load" and "Enable expert users to work quickly"
Source
Extracted from User Experience Analysis discussion #13994
Priority
High - This is the primary configuration reference page, visited by every user creating or modifying workflows. Immediate UX improvement.
AI generated by Discussion Task Miner - Code Quality Improvement Agent
- expires on Feb 7, 2026, 5:23 AM UTC
Activity
github-actions commentedon Feb 7, 2026
This issue was automatically closed because it expired on 2026-02-07T05:23:43.470Z.