[cli-consistency] CLI Consistency Issues - Help Flag Descriptions and Terminology

[github-actions]

Summary

Automated CLI consistency inspection found 2 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.

Inspection Details

• Total Commands Inspected: 33 (including main help, all subcommands, and variations)
• Commands Affected: 30+ (help flag descriptions and terminology)
• Date: 2026-03-10
• Method: Executed all CLI commands with --help flags and analyzed actual output

Breakdown by Severity

• High: 0 (No breaking issues)
• Medium: 1 (Help flag description inconsistency)
• Low: 1 (Terminology inconsistency)

---

Issues Found

Issue 1: Help Flag Description Inconsistency (MEDIUM PRIORITY)

Type: Inconsistent flag descriptions
Affected: All subcommands (30+ variations found)

Current Output Examples

$ ./gh-aw --help
  -h, --help      Show help for gh aw

$ ./gh-aw add --help
  -h, --help                       help for add

$ ./gh-aw compile --help
  -h, --help                       help for compile

$ ./gh-aw audit --help
  -h, --help            help for audit
```

#### Issue Description
The `-h, --help` flag descriptions are inconsistent across commands:
- **Main help**: "Show help for gh aw"
- **Subcommands**: "help for [command]" (e.g., "help for add", "help for compile", "help for audit")
- **Total variants**: 30+ different descriptions found

This inconsistency violates CLI best practices where common flags should have consistent descriptions across all commands.

#### Suggested Fix
Standardize all help flag descriptions to match the main command. Options:
1. **Option A** (descriptive): "Show help for gh aw [command]"
2. **Option B** (concise): "Show help" (common in Unix tools)

**Recommendation**: Use **"Show help for gh aw"** for all subcommands to match main help style, or consider using brief descriptions like other global flags.

---

### Issue 2: Terminology Inconsistency (LOW PRIORITY)

**Type**: Mixed terminology across help text  
**Severity**: May confuse users about terminology

#### Terminology Usage
```
- "agentic workflow": 52 occurrences (primary term)
- "workflow file": 16 occurrences (secondary term)  
- "workflow Markdown": 6 occurrences (specific context)

Issue Description

The help text uses mixed terminology to describe the same concept:

• Some commands refer to "agentic workflow"
• Others refer to "workflow file"
• A few use "workflow Markdown"

While context-dependent use of "workflow file" is valid (when referring to the .md file), the primary terminology should be consistent.

Current Examples

• add command: "Add one or more workflows from repositories" (uses generic "workflow")
• status command: "Show status of all agentic workflows" (uses "agentic workflow")
• remove command: References both "workflow" and "workflow file"

Suggested Fix

Establish consistent terminology:

1. Primary term: "agentic workflow" (appears most frequently, most descriptive)
2. Secondary term: Use "workflow file" ONLY when specifically referring to the .md file itself
3. Technical context: Reserve "workflow Markdown" for documentation about the format

Apply consistently across all command help text to avoid user confusion.

---

Areas Verified ✓

✅ No Critical Issues: No commands are broken or non-functional
✅ All Commands Work: All 33 commands respond properly to --help
✅ No Spelling Errors: No obvious typos or spelling mistakes found
✅ Help Format Completeness: All commands have proper help documentation
✅ Examples Provided: Most commands include practical usage examples
✅ Flag Documentation: All flags are documented with descriptions

---

Inspection Coverage

Commands tested and verified:

• Main help and global flags ✓
• Setup commands: add, add-wizard, init, new, remove, secrets, update, upgrade ✓
• Development commands: compile, fix, list, mcp (+ subcommands), status, validate ✓
• Execution commands: disable, enable, run, trial ✓
• Analysis commands: audit, checks, health, logs ✓
• Utilities: completion, hash-frontmatter, mcp-server, pr (+ subcommands), project, help ✓
• Version command: version ✓

---

Recommendations

High Priority

• Standardize -h, --help flag descriptions across all commands for consistency

Medium Priority

• Consider standardizing terminology to use "agentic workflow" as primary term
• Document which term should be used in which context (workflow file vs agentic workflow)

Low Priority

• Consider adding a terminology glossary to CLI documentation
• Review other flag descriptions for similar inconsistencies in future improvements

Generated by CLI Consistency Checker · ◷

• expires on Mar 12, 2026, 1:51 PM UTC