name: review-cross-command-consistency description: "Compares sibling command classes for consistent structure, documentation, testing, and exit-status conventions under the Base architecture. Use for cross-command audits."

Review Cross-Command Consistency

Review sibling command classes (same module/family) for consistent structure, documentation, testing, and exit-status conventions under the Base architecture.

Contents

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the sibling command files (same module/family) to compare. Examples:

Using the Review Cross-Command Consistency skill, review the
Git::Commands::Diff family: lib/git/commands/diff/patch.rb,
lib/git/commands/diff/numstat.rb, lib/git/commands/diff/raw.rb.

Review Cross-Command Consistency: all files under lib/git/commands/stash/

The invocation needs two or more sibling command files from the same family.

Prerequisites

Before starting, you MUST load the following skill(s) in their entirety:

  • YARD Documentation — authoritative source for YARD formatting rules and writing standards;

Version-Aware Comparison Scope

Before flagging siblings as inconsistent for option names, aliases, negated forms, or documented values, determine the repository's minimum supported Git version from project metadata. In this repository, git.gemspec declares git 2.28.0 or greater.

Consistency judgments for CLI surface area must be based on the minimum supported Git version, not only on the locally installed Git. Use version-matched upstream documentation first, version-matched upstream source when exact parser behavior is ambiguous, and local git <command> -h output only as a supplemental check.

What to Check

1. Class structure consistency

  • [ ] all classes use class < Git::Commands::Base
  • [ ] all require git/commands/base
  • [ ] all use arguments do ... end (no legacy ARGS = constants)
  • [ ] simple commands carry YARD directive # @!method call(*, **) with nested @overload blocks and have no explicit def call definition
  • [ ] commands with legitimate call overrides (stdin protocol, input validation, non-trivial option routing) use explicit YARD docs instead and do not carry the # @!method directive
  • [ ] commands with call overrides use Base#with_stdin for stdin feeding and delegate exit-status validation to validate_exit_status!

2. Arguments DSL consistency

  • [ ] shared options use same alias/modifier patterns
  • [ ] shared entries appear in same relative order
  • [ ] command-specific differences are intentional and documented
  • [ ] no literal entries for policy/output-control flags (--no-edit, --verbose, --no-progress, --no-color, etc.) — command classes are neutral, faithful representations of the git CLI; all siblings use flag_option / value_option for these, leaving policy decisions to the facade. See "Command-layer neutrality" in CONTRIBUTING.md.

3. Exit-status consistency

  • [ ] siblings with same git exit semantics use same allow_exit_status range
  • [ ] rationale comments are present and consistent in tone
  • [ ] commands without non-zero successful exits do not declare custom ranges

4. YARD consistency

  • [ ] consistent class summaries and @api private
  • [ ] @overload coverage consistent for equivalent call shapes
  • [ ] @return and @raise wording consistent across siblings — @raise [Git::FailedError] uses the canonical generic form ("if git exits with a non-zero exit status" for default range; "if git exits outside the allowed range (exit code > N)" for non-default); never enumerates specific failure causes
  • [ ] tag short descriptions do not end with punctuation
  • [ ] multi-paragraph tag descriptions have a blank comment line between the short description and each continuation paragraph

5. Unit spec consistency

  • [ ] expectations include raise_on_failure: false where command invocation is asserted
  • [ ] similar option paths use similar context naming
  • [ ] exit-status tests are parallel where ranges are shared

6. Integration spec consistency

  • [ ] success/failure grouping uses same structure
  • [ ] no output-format assertions (smoke + error handling only)

7. Migration process consistency

See Command Implementation § Phased rollout requirements for the canonical checklist. During a cross-command audit, verify that sibling commands were migrated in the same slice and that the same quality gates were applied.

Output

  1. Summary table:

    Aspect File A File B File C Status

  2. Inconsistency list with canonical recommendation:

    Issue Files Recommended canonical form

Branch workflow: Implement any fixes on a feature branch. Never commit or push directly to main — open a pull request when changes are ready to merge.