Review Arguments Dsl
Testing & Qualityreview-arguments-dslReview Arguments Dsl is an Agent Skill for testing & quality published in the ruby-git/ruby-git repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Audits a command class's arguments DSL definition to verify it accurately maps Ruby call arguments to git CLI arguments in the correct order with correct DSL methods and modifiers.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ruby-git/ruby-git/blob/HEAD/.github/skills/review-arguments-dsl/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/review-arguments-dsl, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Review Arguments DSL
Verify that a command class's arguments do ... end definition accurately maps Ruby
call arguments to git CLI arguments, in the correct order, with the correct DSL
methods and modifiers.
Contents
Related skills
- Command Implementation — class structure, phased rollout gates, and internal compatibility contracts
- Command Test Conventions — unit/integration test conventions for command classes
- Command YARD Documentation — documentation completeness for command classes
Input
What the agent requires to run this skill and where to get it.
Command source code
Read the command class from lib/git/commands/{command}.rb or, for subcommands,
lib/git/commands/{command}/{subcommand}.rb. For subcommands, also read the
namespace module at lib/git/commands/{command}.rb which should list all sibling
subcommands and provide the module-level documentation.
Command test code
Read unit tests matching spec/unit/git/commands/{command}/**/*_spec.rb. Use these as
supplemental evidence when tracing the verification chain (Ruby call → bound
argument → expected git CLI). Coverage completeness is assessed by the
Command Test Conventions skill.
Git documentation for the git command
-
Latest-version online command documentation
Read the entire official git documentation online man page for the command for the latest version of git. This version will be used as the primary authority for DSL completeness, including the options to include in the DSL, argument names, aliases, ordering, etc. Fetch this version from the URL
https://git-scm.com/docs/git-{command}(this URL always serves the latest release). -
Minimum-version online command documentation
Read the entire official git documentation online man page for the command for the
Git::MINIMUM_GIT_VERSIONversion of git. This will be used only for command-introduction andrequires_git_versiondecisions. Fetch this version from URLhttps://git-scm.com/docs/git-{command}/{version}.
Do not scaffold from local git <command> -h output alone — the installed Git
version is unknown and may differ from the latest supported version. Local help should
NOT be used even as a supplemental check.
Reference
Architecture Context (Base Pattern)
Command classes follow this structure:
class < Git::Commands::Base- class-level
arguments do ... end - optional class-level macros such as
allow_exit_status <range>andrequires_git_version <version> - YARD documentation with
@overloadblocks containing@param,@option,@return, and@raisetags, in one of two forms:- when
#callis overridden: standard YARD comments directly abovedef call - when
#callis not overridden: a# @!method call(*, **)directive with nested standard YARD comments
- when
The CLI argument mapping is still defined exclusively by the Arguments DSL. The
Base class handles binding and execution.
DSL to CLI Mapping
The Arguments DSL (arguments do ... end) declares how Ruby keyword and positional
arguments map to git CLI flags, options, and operands. See CHECKLIST.md §
Verify DSL method per option type
for the full DSL method mapping table.
Key behaviors:
- Basic emit —
flag_option :verbose→--verbose;value_option :message→--message <value>;operand :commit→ bare<value>in positional slot. flag_or_value_option— hybrid:true→--flag; string →--flag value(or--flag=valuewithinline:);false/nil→ nothing. Supportsnegatable:.key_value_option— accepts a Hash or Array of pairs; emits--flag key=valueper pair.key_separator:overrides=;inline:joins as--flag=key=value.custom_option— block receives the raw value and returns CLI strings; String is appended, Array is concatenated,nil/empty emits nothing.- nil / false suppression — for boolean-style options (
flag_option,flag_or_value_optionin boolean mode),falseornilsuppresses emission. Forvalue_option/inline_valueoptions,falseis treated as a value (stringified to"false") unless a type constraint rejects it.nilsuppresses emission for all option types (including negatable options —falseis absent, not--no-*). - Output order matches definition order — bound arguments are emitted in the
order entries appear in
arguments do. - Name-to-flag mapping — underscores become hyphens, single-char names map to
-x, multi-char names map to--name. Case is preserved::A→-A,:N→-N. Uppercase short flags do not requireas:. as:override — emits a verbatim string instead of deriving the flag from the symbol name. See CHECKLIST.md § Theas:escape hatch for when use is justified.- Aliases — first alias is canonical and determines the generated flag; remaining
aliases are accepted as caller-side synonyms. Long name first:
%i[force f], not%i[f force]. negatable:— registers two entries: the positive key and ano_companion. Both follow standard boolean semantics:trueemits the flag,false/nilomits it. Passno_edit: trueto emit--no-edit.flag_option :edit, negatable: true→:edit[Boolean]and:no_edit[Boolean]flag_or_value_option :track, negatable: true→:track[Boolean, String](positive or value form) and:no_track[Boolean](boolean only; the negated form never takes a value)
inline:—value_option :format, inline: trueemits--format=valueas one token; without it,--format valueas two tokens.max_times:—flag_option :force, max_times: 2withforce: 2emits--force --force.repeatable:— accepts an array; emits the flag once per value (e.g.,--include a --include b).as_operand:—value_option :pathspec, as_operand: trueis passed as a keyword but emitted in the operand position afterend_of_options.literal— always emits its string unconditionally; the caller has no control.execution_option— never emits anything to argv; forwarded as Ruby kwargs to the subprocess runner.skip_cli:on operands —operand ..., skip_cli: truebinds and validates like any other operand and remains accessible onBound, but is excluded from argv emission.end_of_options— signals end of options in the emitted argv; only operands may follow (though operands may also appear before it). Emits--by default. Override withas:when the command uses a different token. See CHECKLIST.md § Choosing theas:token for the decision rule.- Operand/option name collision — if a positional operand and a keyword option
share the same name, the option keeps its name and the operand is renamed.
For repeatable operands, prefer the plural form (
:commit→:commits). See CHECKLIST.md § Operand naming for details.
Workflow
-
Determine scope and exclusions — using the git documentation loaded during Input, identify which options are in scope for the DSL. See CHECKLIST.md §1.
-
Audit each DSL entry — for each entry in
arguments do, walk through CHECKLIST.md §2–§5:- Verify DSL method per option type
- Verify alias and
as:usage - Verify ordering
- Verify modifiers
For each entry, also trace the verification chain — confirm the full mapping:
Ruby call → bound argument → expected git CLICompare the expected CLI output against the git man-page documentation.
-
Check completeness — verify the DSL as a whole against the git man page per CHECKLIST.md §6: YARD↔DSL parity, missing options, repeatable flags, operand naming, and per-argument validation.
-
Check class-level declarations — verify
allow_exit_statusandrequires_git_versionper CHECKLIST.md §7. -
Check the validation delegation policy — verify that cross-argument constraint methods (
conflicts,requires, etc.) are used only when justified. See the constraint policy in CHECKLIST.md §6 Per-argument validation completeness. -
Collect issues — record all findings for the Output.
Output
Produce:
-
A per-entry table:
# DSL method Definition CLI output Correct? Issue -
A list of missing options/modifier/order/conflict issues
-
Any class-level declaration mismatches:
allow_exit_statusnot present with aRangeand rationale comment when the command has non-zero successful exits;requires_git_versionnot present only when the command was introduced afterGit::MINIMUM_GIT_VERSION