Add workflow guidance and cross-references to CLI help text

[Copilot]

CLI help text lacked actionable guidance for typical command sequences and error recovery patterns.

Changes

Added two sections to help text for compile, add, update, fix, and trial commands:

Common Workflows - Shows typical multi-command sequences:

# Check for errors before compiling
gh aw fix                        # Dry-run to check for deprecated fields
gh aw fix --write                # Fix issues automatically

# Compile and validate a new workflow
gh aw compile my-workflow
gh aw compile my-workflow --validate  # With schema validation

# If compilation fails, debug with hash command
gh aw hash my-workflow           # Check frontmatter rendering

Related Commands - Cross-references to related commands:

Related Commands:
  gh aw fix       Apply automatic fixes before compiling
  gh aw hash      Debug frontmatter and expression issues
  gh aw logs      View workflow execution logs after running
  gh aw health    Check workflow success rates and trends

Example

$ gh aw compile --help
...
Common Workflows:
  # Check for errors before compiling
  gh aw fix                        # Dry-run to check for deprecated fields
  gh aw fix --write                # Fix issues automatically

  # Compile and validate a new workflow
  gh aw compile my-workflow
  gh aw compile my-workflow --validate  # With schema validation

  # If compilation fails, debug with hash command
  gh aw hash my-workflow           # Check frontmatter rendering

  # After deployment, monitor execution
  gh aw run my-workflow            # Test run the workflow
  gh aw logs my-workflow           # Check recent execution logs
  gh aw health my-workflow         # View success rates

Related Commands:
  gh aw fix       Apply automatic fixes before compiling
  gh aw hash      Debug frontmatter and expression issues
  gh aw logs      View workflow execution logs after running
  gh aw health    Check workflow success rates and trends

Each command's workflows are tailored to its typical usage patterns - trial shows trial→logs→add sequences, update shows update→compile→test flows, etc.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Improve CLI command help text with actionable next steps</issue_title>
<issue_description>## 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 github/gh-aw#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

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Improve CLI command help text with actionable next steps #14248

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Updates the gh aw CLI help text to provide more actionable guidance by adding “Common Workflows” and “Related Commands” cross-references to several commonly used commands.

Changes:

• Added “Common Workflows” sections showing multi-step usage sequences (e.g., fix → compile → run).
• Added “Related Commands” sections to cross-link adjacent commands for discovery and troubleshooting.
• Expanded examples/help text for compile, add, update, fix, and trial.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
cmd/gh-aw/main.go	Extends compile --help output with workflow guidance and related command references.
pkg/cli/add_command.go	Adds workflow sequences and related commands to add help text.
pkg/cli/fix_command.go	Adds workflow sequences and related commands to fix help text.
pkg/cli/trial_command.go	Adds workflow sequences and related commands to trial help text.
pkg/cli/update_command.go	Adds workflow sequences and related commands to update help text.

Comments suppressed due to low confidence (2)

pkg/cli/trial_command.go:119

• These examples also use gh aw logs --trial, but logs has no --trial flag. Replace with a valid logs/audit invocation so users can actually view the results of the comparison run.

  # Compare multiple workflow versions
  ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/workflow@v1.0 githubnext/agentics/workflow@v2.0
  ` + string(constants.CLIExtensionPrefix) + ` logs --trial                                        # Compare results

pkg/cli/trial_command.go:123

• These examples also use gh aw logs --trial, but logs has no --trial flag. Replace with a valid logs/audit invocation for trial runs (likely using --repo / run-id output).

  # Debug workflow issues in isolation
  ` + string(constants.CLIExtensionPrefix) + ` trial ./my-workflow.md --clone-repo myorg/myrepo --repeat 3
  ` + string(constants.CLIExtensionPrefix) + ` logs --trial                                        # Analyze trial logs

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The help text suggests using --dry-run, but the command currently returns an error (--dry-run mode not yet implemented for workflow updates). This is misleading for users; either remove the --dry-run example/mention from help text for now, or implement --dry-run behavior before advertising it.

[Copilot]

The help text uses gh aw logs --trial, but the logs command does not define a --trial flag. Update these workflow examples to use a valid invocation (e.g., gh aw logs --repo <trial-host-repo> <workflow> or direct users to gh aw audit <run-id> based on what trial outputs).

This issue also appears in the following locations of the same file:

• line 116
• line 120

[Copilot]

The help text references gh aw hash, but the actual command name is hash-frontmatter (see pkg/cli/hash_command.go). Also, hash-frontmatter expects a workflow file path (e.g., my-workflow.md), not a workflow id. Update the example and the related-commands entry accordingly.

[Copilot]

hash is not an actual CLI command here; the command is hash-frontmatter, and it expects a workflow file path. Update this related-command reference so it matches the real command users can run.

Suggested change

	` + string(constants.CLIExtensionPrefix) + ` compile Use --fix flag for automatic fixing before compile
	` + string(constants.CLIExtensionPrefix) + ` update Automatically applies fixes after updating workflows
	` + string(constants.CLIExtensionPrefix) + ` hash Debug frontmatter issues after fixing`,
	` + string(constants.CLIExtensionPrefix) + ` compile Use --fix flag for automatic fixing before compile
	` + string(constants.CLIExtensionPrefix) + ` update Automatically applies fixes after updating workflows
	` + string(constants.CLIExtensionPrefix) + ` hash-frontmatter my-workflow.yml Debug frontmatter issues after fixing`,

[Copilot]

This example uses --pr, but the add command intentionally hides --pr from help output (MarkHidden("pr")). To avoid advertising a hidden/back-compat flag, use the documented flag name (--create-pull-request) in the workflow example instead.

Suggested change

	` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --pr
	` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --create-pull-request