Current Experience

The compile command is described as:

Short: "Compile all Markdown files"

Enterprise users don't understand what "compile" produces or why this step is necessary, which leads to confusion during initial setup.

Issue

Design Principle: Clarity and Precision

The help text fails to explain:

1. What file format gets produced (.lock.yml)
2. Why the compilation step exists (GitHub Actions requires YAML)
3. That compiled files are required for workflow execution

New users often ask: "I edited my workflow but it's not working" — usually because they're not aware they need to recompile.

Solution

Update the compile command's short description to be more precise:

Before:

Short: "Compile all Markdown files"

After:

Short: "Compile workflow markdown files (.md) into GitHub Actions workflows (.lock.yml)"

This tells users in a single sentence:

• Input format: markdown files (.md)
• Output format: lock files (.lock.yml)
• Purpose: GitHub Actions transformation

Impact

• User Experience: New users understand the compilation pipeline without consulting docs
• Clarity: Help text becomes self-documenting
• Support: Reduces confusion about the role of compiled vs. source files

File to Modify

• cmd/gh-aw/main.go - Only this file needs to change
• Located in the compile command definition
• Change is 1 line and fully backward compatible

Success Criteria

• Help text updated to include file formats
• Help text remains under 80 characters
• Users can understand input/output from help text alone

📊 User experience analysis by Delight · ◷

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