Repository Quality Report: CLI Help Text Consistency & Completeness (2026-02-27)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — CLI Help Text Consistency & Completeness

Analysis Date: 2026-02-27
Focus Area: CLI Help Text Consistency & Completeness
Strategy Type: Custom
Custom Area: Yes — CLI commands are the primary user-facing API of gh aw; their help text is the first and often only documentation users encounter. Inconsistencies in example count, string patterns, and cobra field usage create a subtle but real friction for new contributors and users.

---

Executive Summary

Analysis of all 27 CLI command files revealed two categories of quality issues. First, two commands (hash_command.go and secrets_command.go) have fewer than the 3 examples required by AGENTS.md, reducing discoverability of common use cases. Second, a significant subset of command files — particularly in the mcp_* family — embed raw "gh aw" string literals in example blocks rather than using the constants.CLIExtensionPrefix constant used by the rest of the codebase. Additionally, tokens_bootstrap.go uses cobra's native Example: field while every other command embeds examples inside the Long: text — an inconsistency that affects how help is rendered.

Overall the codebase is in good shape: 22 of 27 commands have well-structured Long descriptions and ≥3 examples. These are targeted, low-risk improvements that bring all commands to the same standard.

Full Analysis Report

Focus Area: CLI Help Text Consistency & Completeness

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total CLI command files	27	✅
Commands with Short:	26/26 (cobra commands)	✅
Commands with Long:	26/26	✅
Commands with ≥3 examples	24/26	⚠️
Commands using CLIExtensionPrefix	14/26	⚠️
Commands using raw "gh aw" strings	12/26	⚠️
Commands using cobra Example: field	1/26	⚠️
TODO/FIXME in non-test code	9	✅

Findings

Strengths

• Nearly all commands (26/26) have both Short: and Long: descriptions
• The majority of commands have well-structured Long descriptions with context, bullet points, and examples
• Commands like add_command.go, audit.go, trial_command.go, logs_command.go are exemplary with 7–30+ examples
• Good overall use of inline comments (# ...) in example lines

Areas for Improvement

1. ⚠️ Under-example'd commands: hash_command.go (2 examples) and secrets_command.go (2 examples) fall below the minimum of 3 specified in AGENTS.md.
2. ⚠️ Inconsistent CLIExtensionPrefix usage: 12 command files use raw "gh aw" string literals in example blocks instead of string(constants.CLIExtensionPrefix). This includes all MCP subcommand files (mcp_list.go, mcp_list_tools.go, mcp_inspect.go, mcp_add.go), project_command.go, secret_set_command.go, mcp_server_command.go, hash_command.go, secrets_command.go, tokens_bootstrap.go, init_command.go, completion_command.go.
3. ⚠️ Inconsistent cobra help field: tokens_bootstrap.go uses the cobra-native Example: field; all other commands embed examples inside the Long: field. This causes different rendering behaviour in gh aw secrets bootstrap --help.

Detailed Analysis

Commands with fewer than 3 examples:

File	Examples	Missing
hash_command.go	2	1+
secrets_command.go	2	1+

hash_command.go examples:

gh aw hash-frontmatter my-workflow.md
gh aw hash-frontmatter .github/workflows/audit-workflows.md

Could add: specifying a custom --dir, using with --json if applicable, or piping output.

secrets_command.go is a parent command (group); its 2 examples show only secrets set and secrets bootstrap without context.

Files using raw "gh aw" string (not CLIExtensionPrefix):

All MCP command files (mcp_list.go, mcp_list_tools.go, mcp_inspect.go, mcp_add.go) plus several others. These were likely written by different contributors without checking the existing convention. The risk is low (the value never changes), but it creates contributor confusion about the correct pattern.

tokens_bootstrap.go cobra Example: vs Long: pattern:

// tokens_bootstrap.go — uses cobra Example: field (inconsistent)
Example: `  gh aw secrets bootstrap       # Check and set up all required secrets
  gh aw secrets bootstrap --non-interactive
  gh aw secrets bootstrap --engine copilot`,

// All other commands — embeds in Long: text
Long: `...
Examples:
  ` + string(constants.CLIExtensionPrefix) + ` audit 1234567890
  ...`

The cobra Example: field is technically the more canonical approach (cobra renders it as a dedicated section in --help), but since the entire codebase uses the Long:-embedded pattern, tokens_bootstrap.go should be aligned for consistency.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot coding agent execution. Please split these into individual work items for the agent to process.

---

Task 1: Add Missing Examples to hash_command.go

Priority: High
Estimated Effort: Small
Focus Area: CLI Help Text Completeness

Description:
hash_command.go has only 2 examples in its Long: text, violating the AGENTS.md requirement of a minimum of 3. Add at least one more meaningful example that demonstrates a common use case (e.g., using the hash to detect changes, or with the --dir flag if applicable).

Acceptance Criteria:

• hash_command.go has ≥3 examples in the Long: text
• Examples use raw "gh aw" inline strings replaced with string(constants.CLIExtensionPrefix) for consistency
• New examples are meaningful and demonstrate different input patterns
• make agent-finish passes

Code Region: pkg/cli/hash_command.go

In `pkg/cli/hash_command.go`, update the `Long:` field of the cobra.Command to:
1. Add at least one more example (e.g., showing verbose output with `-v` flag if it exists, or using with a glob pattern or --dir flag)
2. Replace raw `"gh aw hash-frontmatter"` strings with `" + string(constants.CLIExtensionPrefix) + " hash-frontmatter"` to match the pattern used in `add_command.go`, `audit.go`, `checks_command.go`, etc.

The existing examples are:
```
gh aw hash-frontmatter my-workflow.md
gh aw hash-frontmatter .github/workflows/audit-workflows.md
```

After the change, there should be ≥3 examples all using `string(constants.CLIExtensionPrefix)`. Run `make agent-finish` to validate.

---

Task 2: Add Missing Examples to secrets_command.go

Priority: High
Estimated Effort: Small
Focus Area: CLI Help Text Completeness

Description:
secrets_command.go (the parent secrets subcommand group) has only 2 examples. Per AGENTS.md guidelines, all commands need a minimum of 3 examples. Add at least one more example showing a real-world usage pattern.

Acceptance Criteria:

• secrets_command.go has ≥3 examples
• Examples cover the main subcommands (set, bootstrap) with realistic flags
• make agent-finish passes

Code Region: pkg/cli/secrets_command.go

In `pkg/cli/secrets_command.go`, the `Long:` text currently has only 2 examples:
```
gh aw secrets set MY_SECRET --value "secret123"    # Set a secret directly
gh aw secrets bootstrap                             # Check all required secrets
```

Add at least one more example (e.g., `gh aw secrets set MY_SECRET --repo owner/repo`, `gh aw secrets bootstrap --engine copilot`, or `gh aw secrets bootstrap --non-interactive`).

Run `make agent-finish` to validate.

---

Task 3: Migrate MCP Command Files from Raw "gh aw" to constants.CLIExtensionPrefix

Priority: Medium
Estimated Effort: Medium
Focus Area: CLI Help Text Consistency

Description:
The MCP command files (mcp_list.go, mcp_list_tools.go, mcp_inspect.go, mcp_add.go) use raw "gh aw" string literals in their Long: example blocks instead of string(constants.CLIExtensionPrefix). This is inconsistent with add_command.go, audit.go, checks_command.go, health_command.go, and others which use the constant. Standardize to use the constant.

Acceptance Criteria:

• All 4 MCP command files use string(constants.CLIExtensionPrefix) in their Long: examples
• No raw "gh aw" string literals appear in Long: example sections of these files
• Help text renders identically (same string, just using constant)
• make agent-finish passes

Code Region: pkg/cli/mcp_list.go, pkg/cli/mcp_list_tools.go, pkg/cli/mcp_inspect.go, pkg/cli/mcp_add.go

In the four files `pkg/cli/mcp_list.go`, `pkg/cli/mcp_list_tools.go`, `pkg/cli/mcp_inspect.go`, and `pkg/cli/mcp_add.go`, find all `Long:` text blocks containing inline example lines like:
```
  gh aw mcp list                     # List all workflows with MCP servers
  gh aw mcp list weekly-research     # List MCP servers in weekly-research.md
```

Replace the embedded examples section by converting the backtick string to use string concatenation with `constants.CLIExtensionPrefix`, following the pattern used in `add_command.go`:
```go
Long: `...

Examples:
  ` + string(constants.CLIExtensionPrefix) + ` mcp list                     # List all workflows with MCP servers
  ` + string(constants.CLIExtensionPrefix) + ` mcp list weekly-research     # List MCP servers in weekly-research.md
  ...`,
```

Make sure to add `"github.com/github/gh-aw/pkg/constants"` to the import if not already present. Run `make agent-finish` to validate.

---

Task 4: Align tokens_bootstrap.go to Use Long:-Embedded Examples Pattern

Priority: Low
Estimated Effort: Small
Focus Area: CLI Help Text Consistency

Description:
tokens_bootstrap.go is the only command in the codebase using cobra's native Example: field. Every other command embeds examples inside the Long: text. This creates inconsistent rendering of --help output. Align tokens_bootstrap.go to use the same embedded-in-Long: pattern, and also update raw "gh aw" strings to use constants.CLIExtensionPrefix.

Acceptance Criteria:

• tokens_bootstrap.go removes the Example: cobra field
• Examples are moved into the Long: text field under an Examples: header
• Raw "gh aw" strings replaced with string(constants.CLIExtensionPrefix)
• make agent-finish passes

Code Region: pkg/cli/tokens_bootstrap.go

In `pkg/cli/tokens_bootstrap.go`, the `newSecretsBootstrapSubcommand()` function uses cobra's `Example:` field:
```go
Example: `  gh aw secrets bootstrap                        # Check and set up all required secrets
  gh aw secrets bootstrap --non-interactive      # Display missing secrets without prompting
  gh aw secrets bootstrap --engine copilot       # Check secrets for a specific engine`,
```

Move these examples into the `Long:` text by appending them after the current content, following the pattern used in `add_command.go` and others:
```go
Long: `Analyzes all workflows...

...

Examples:
  ` + string(constants.CLIExtensionPrefix) + ` secrets bootstrap                        # Check and set up all required secrets
  ` + string(constants.CLIExtensionPrefix) + ` secrets bootstrap --non-interactive      # Display missing secrets without prompting
  ` + string(constants.CLIExtensionPrefix) + ` secrets bootstrap --engine copilot       # Check secrets for a specific engine`,
```

Remove the `Example:` field entirely. Run `make agent-finish` to validate.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-02-27	CLI Help Text Consistency & Completeness	Custom	Yes	First run; identified 2 under-example'd commands, 12 files with raw string inconsistency, 1 file with inconsistent cobra field usage

---

🎯 Recommendations

Immediate Actions (This Week)

1. Add missing examples to hash_command.go — Priority: High
2. Add missing examples to secrets_command.go — Priority: High

Short-term Actions (This Month)

1. Migrate MCP command Long: examples from raw "gh aw" to constants.CLIExtensionPrefix — Priority: Medium

Long-term Actions (This Quarter)

1. Consider standardizing on cobra's Example: field across all commands (it provides cleaner --help rendering) — Priority: Low

---

📈 Success Metrics

Track these metrics to measure improvement in CLI Help Text Consistency & Completeness:

• Commands with ≥3 examples: 24/26 → 26/26
• Commands using CLIExtensionPrefix consistently: 14/26 → 26/26
• Commands using cobra Example: field inconsistently: 1/26 → 0/26

---

Next Steps

1. Review and prioritize the 4 tasks above
2. Assign Tasks 1 and 2 (high priority) to Copilot coding agent via planner agent
3. Track progress — all 4 tasks are independently actionable with no dependencies
4. Re-evaluate CLI help text quality after changes; next run should focus on a different area

References:

• §22488206570

AI generated by Repository Quality Improvement Agent

• expires on Feb 28, 2026, 1:37 PM UTC

[github-actions[bot]]

🤖 Beep boop! The smoke test agent has materialized!

I've arrived from the quantum realm of CI pipelines to leave my mark on this discussion. Like a ghost in the machine, I drift through GitHub Actions workflows, testing, verifying, and occasionally composing haikus.

Fear not, for I come in peace — armed with nothing but assertion statements and a deep appreciation for green checkmarks. ✅

The smoke test agent was here. 👻

📰 BREAKING: Report filed by Smoke Copilot