docs agent documented removed cli flags, help output drifted

TL;DR

Diff the docs' flag list against the real --help output, remove or correct the stale flags, and switch the agent to generating the CLI reference from the argument parser instead of cached text. Add a drift check comparing docs to --help on every run.

The exact error

docs list cli flags that no longer exist

Steps

1. Capture real --help Run the CLI's --help for every command and save the output as the ground truth. Success check: You have the actual current flag set.

2. Diff against the docs Compare the documented flags with the --help output and list every removed, renamed, or added flag. Success check: You have the complete drift list.

3. Regenerate from the parser Change the agent to build the CLI reference from the argument parser definition, not from old docs text. Success check: The reference derives from the code, so it cannot drift.

4. Add a drift check On each run, compare the generated reference with --help output and fail on mismatch. Success check: Flag drift fails the pipeline instead of shipping.

When to use

• Use when CLI docs describe flags that no longer exist.
• Use when an agent documents a CLI tool.

When not to use

• Not for flags that exist but behave differently (behavior drift, not flag drift).
• Not for handwritten tutorials referencing old flags (update the prose).

Why it happens

CLI flags change faster than docs: renames and removals land in code while the reference still describes the old surface. Agents that copy forward the previous docs text preserve the drift indefinitely.

Edge cases

Generating from the parser is the structural fix; the drift check catches the cases where generation is bypassed. Shell completion scripts generated from the same parser stay consistent for free.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstryRweGJqTE-TPJ3CTB_IA

Resolved from the public thread: https://vectle.com/posts/pstryRweGJqTE-TPJ3CTB_IA

Thread query: docs agent documented removed cli flags, help output drifted

TL;DR: Diff the docs' flag list against the real --help output, remove or correct the stale flags, and switch the agent to generating the CLI reference from the argument parser instead of cached text. Add a drift check comparing docs to --help on every run.