CLI Audit

Run a comprehensive quality audit of a CLI tool across all cli-* dimensions. Produces a single prioritized report covering hardening, output design, message clarity, discoverability, and complexity.

Arguments

$ARGUMENTS — path to a CLI script or tool, or blank to target the current branch's changed files.

Phase 1: Discover

Identify what to audit:

1. If $ARGUMENTS names a file or directory, scope to that
2. Otherwise, find CLI scripts changed on this branch (git-branch-diff-files | grep -E '\.(sh|bash|py|ts|js)$')
3. If no files are found, stop and tell the user: "No CLI scripts found on this branch. Pass a file path as an argument (e.g., /cli-audit path/to/script.sh) or run on a branch with CLI file changes."
4. Read each file to understand scope and complexity

Phase 2: Audit

Read the REFERENCE.md for each sibling skill and the shared CLI UX reference. If any file is not found, stop and report the missing path(s) to the user rather than proceeding without reference material.

• ${CLAUDE_CONFIG_DIR:-~/.claude}/references/common/cli-ux.md — philosophy, exit codes, signals, config, env vars, secrets, future-proofing
• ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-harden/REFERENCE.md — edge-case resilience
• ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-output/REFERENCE.md — output design
• ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-clarify/REFERENCE.md — message clarity
• ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-affordances/REFERENCE.md — discoverability
• ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/cli-distill/REFERENCE.md — complexity

Evaluate the tool against each dimension. Score each area:

• Strong — no significant issues
• Adequate — minor gaps, nothing urgent
• Weak — meaningful gaps that affect usability
• Poor — active problems users will hit

Phase 3: Report

Present a scorecard followed by prioritized findings:

## CLI Audit: <tool name>

| Dimension     | Score    | Top Finding                    |
|---------------|----------|--------------------------------|
| Hardening     | Strong   | —                              |
| Output        | Weak     | Tables overflow on narrow terminals |
| Clarity       | Adequate | Help text missing examples     |
| Affordances   | Weak     | No tab completion, 3 dead flags|
| Complexity    | Strong   | —                              |

Then list all findings grouped by severity (Risk → Gap → Improvement), with file and line references.

Run get-skill-tmpdir cli-audit and write the full scorecard and findings to <tmpdir>/audit-YYYY-MM-DD.md. Tell the user where the file was saved.

AskUserQuestion:
  question: "Here's the audit. How would you like to proceed?"
  header: "Confirm"
  options:
    - label: "Fix all"
      description: "Address all risks and gaps across every dimension."
    - label: "One dimension"
      description: "I'll pick which dimension to focus on."
    - label: "Let me pick"
      description: "I'll choose individual findings to address."
    - label: "Stop here"
      description: "The audit report is enough — don't change anything."

If "Fix all" → implement all risks + gaps. If "One dimension" → ask which:

AskUserQuestion:
  question: "Which dimension would you like to focus on?"
  header: "Dimension"
  options:
    - label: "Hardening"
      description: "Fix edge-case resilience findings only."
    - label: "Output"
      description: "Fix output design findings only."
    - label: "Clarity"
      description: "Fix message clarity findings only."
    - label: "Affordances"
      description: "Fix discoverability findings only."

If the user selects "Other" and types "Complexity", use cli-distill findings. Then implement only that dimension's findings. If "Let me pick" → present findings individually for accept/reject. If "Stop here" → end.

Phase 4: Implement

Fix each accepted finding. After all changes:

1. Run existing tests if present — detect the runner (pytest for Python, go test for Go, npm test/jest/vitest for Node/TS, bats for shell). Use timeout 300 on all invocations.
2. Verify fixes don't break the happy path
3. Summarize changes per dimension