docs: improve gw help per CLI_RULE.md review - #41
Merged
Conversation
Address the CLI_REVIEW_V1 findings for gw:
- Rule 1: drop builder-jargon "type-safe" from the first line; lead with
user value ("Worktree-aware git workflow: branch -> PR -> cleanup, safely").
- Rule 3/5/8/9/11: add a rich --help (long_about) with a TYPICAL FLOW quick
start, a "home branch" definition, situational command grouping (Everyday /
Recovery / Worktrees), and the named audience -- while keeping -h compact.
clap now signals the divergence with "(see more with '--help')".
- Rule 13: usage errors (bad subcommand, missing arg) now print a "Try:"
footer pointing at a runnable next command (gw status) plus gw --help.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves
gw's--help/-h/error output against the CLI Help Design Rules, targeting the CLI_REVIEW_V1 gw findings (scored 5.5/10).Changes
First line (Rule 1) — dropped the builder-jargon
type-safe worktree-aware git operationsfor user value:--helpnow earns its keystrokes (Rules 3, 5, 8, 9, 11) — added along_aboutshown only on--help, while-hstays a compact command list. It carries:gw new→ commit/push/PR →gw await)clap auto-appends
(see more with '--help')to-h, signalling the divergence (Rule 6).Actionable errors (Rule 13) —
gw <badcmd>/gw await(missing arg) now end with a runnable next command instead of clap's bare footer:--help/--versionstill exit 0; usage errors exit 2.Verification
mise run verifypasses (fmt, clippy, tests, build). Manually checked-h,--help,gw stauts,gw await, baregw,--version.🤖 Generated with Claude Code