[Code Quality] Improve CLI command help text with actionable next steps

[github-actions]

Description

User experience analysis revealed that CLI help text lacks actionable guidance for next steps after errors or common usage patterns. While commands like health have good examples, other commands could benefit from improved help text that guides users through common workflows.

Suggested Changes

1. Add "Common Workflows" section to key commands

Add a "Common Workflows" section to frequently-used commands (compile, add, update, trial) that shows typical usage sequences:

Common Workflows:
  # Add and compile a new workflow
  gh aw add org/repo/workflow.md
  gh aw compile workflow

  # Update and recompile all workflows
  gh aw update
  gh aw compile --all

2. Improve error recovery guidance

When compilation or validation fails, suggest specific next steps:

• gh aw logs workflow to check recent runs
• gh aw health workflow to see success rates
• Common fix patterns for validation errors

3. Add cross-command references

Link related commands in help text:

• logs command mentions health for metrics
• compile mentions hash for frontmatter debugging
• add mentions update for keeping workflows current

Files Affected

Key CLI commands that would benefit most:

• pkg/cli/compile_command.go - Add common compilation workflows
• pkg/cli/add_command.go - Add workflow addition patterns
• pkg/cli/update_command.go - Add update and sync patterns
• pkg/cli/trial_command.go - Add trial testing workflows
• pkg/cli/fix_command.go - Add codemod application examples

Success Criteria

• Each major command (compile, add, update, trial) has "Common Workflows" section
• Help text includes cross-references to related commands
• Error scenarios suggest specific next-step commands
• All examples use consistent format matching existing style
• Changes maintain <80 char short descriptions
• Examples tested and verified working

Source

Extracted from User Experience Analysis discussion #14234

Finding: "CLI help text and validation error messages need improvement with more actionable guidance"

Priority

Medium - Improves developer experience and reduces learning curve but not blocking functionality.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 8, 2026, 1:29 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster

[github-actions]

This issue was automatically closed because it expired on 2026-02-08T01:29:13.784Z.