Evaluate your CLI surface area against the "Simple and Focused" principle, you can use the following prompt. This instructs Claude to look for Flag Bloat, Command Overloading, and Inter-dependency Confusion.
The Evaluation Prompt
"Analyze all Cobra/CLI commands in this project to evaluate their 'Functional Focus' and 'Flag Complexity.' Please provide a report in a Markdown table with the following columns:
Command Name: The full subcommand path (e.g., stave evaluate).
Primary Intent: A one-sentence description of the single job this command performs.
Flag Count: Total number of unique flags.
Complexity Score (1-5):
1 = Do one thing, no flags needed.
5 = 'Swiss Army Knife' (many flags that only work in certain modes).
Refactoring Recommendation: Identify if any flags should be moved to a new subcommand, turned into a default behavior, or split into a separate 'piped' utility.
In your analysis, specifically look for:
'Mode' Flags: Flags like --mode, --dry-run, or --json that radically change the command's output or behavior (these often indicate a hidden subcommand).
Mutually Exclusive Flags: Flags that cannot be used together (e.g., --dir and --file).
Infrastructure vs. Logic Flags: Mixing 'how to run' (e.g., --concurrency) with 'what to check' (e.g., --severity).
The goal is to simplify the CLI so it follows the 'Unix Philosophy' of doing one thing well."
How to use this as a Claude Code Skill
If you want to save this for repeated use during development, you can create a skill:
"Create a skill called audit-cli-complexity. When run, it should scan cmd/ and internal/app/ to identify all CLI flags and subcommands. It should then generate the 'Functional Focus' table described in the evaluation prompt to help me decide which flags to eliminate or split into new commands."
Why this produces "Intent-Revealing" Results:
Identifies "Ghost Commands": Often, a flag like stave evaluate --compare is actually a separate command (stave diff) waiting to be born.
Highlights "Configuration Fatigue": If a command has a Complexity Score of 4 or 5, it reveals that the user's intent is being buried under technical switches.
Enforces Piped Workflows: By suggesting "separate piped utilities," it moves your design toward the "Go Way"—where small tools are composed together rather than one tool being a "God Object."
Example Output to Expect: Command Name Primary Intent Flag Count Complexity Recommendation stave apply Updates security posture 12 4 Split --validate-only into stave validate. stave doctor Checks environment 2 1 Perfect. Keep as is. stave evaluate Runs policy audit 18 5 Move --compare-to-git to a new stave diff command.