P3: Progressive Help Discovery

Definition

Help text MUST be layered so agents (and humans) can drill from a short summary to concrete usage examples without reading the entire manual. The critical layer is the one that appears after the flags list, because that is where readers look for invocation patterns.

Why Agents Need It

Agents discover how to use a tool by calling --help and scanning the output. They skip past flag definitions (which describe what is possible) and hunt for examples (which describe what to do). A flags list alone is enough rope to produce a failed invocation; examples are what turn discovery into action. Without examples in the help output, an agent trial-and-errors its way into a working call, burning tokens and sometimes landing on a wrong-but-silent success.

Requirements

The principle is framework-agnostic. clap's after_help is the worked example below; analogs include cobra's Example (Go), argparse's epilog (Python), docopt's usage block, and the Examples: convention in gh / kubectl.

Evidence

• after_help (or after_long_help) attribute on the top-level parser struct.
• after_help attribute on every subcommand variant.
• Example invocations in after_help text that include realistic arguments, not placeholder <foo> tokens.
• Both about (short) and after_help (examples) present on each subcommand.

Anti-Patterns

• Relying solely on /// doc comments: those populate about / long_about, not after_help, so no examples render after the flags list.
• A single about string serving as both summary and usage documentation.
• Examples buried in a README or man page but absent from --help output.
• after_help text that describes the flags in prose instead of demonstrating them in code.

Measured by audit IDs p3-help, p3-after-help, p3-version. Run anc audit --principle 3 . against the CLI under test to see each.