docs: fail loud on unknown flags (principle 6)#63
Draft
themightychris wants to merge 1 commit into
Draft
Conversation
themightychris
force-pushed
the
docs/fail-loud-unknown-flags
branch
3 times, most recently
from
1ffe28a to
0d3e04f
Compare
Add a "Fail loud on unrecognized input" sub-principle to principle 6 (Structured errors & exit codes): unknown flags and arguments must be rejected with exit 2, never silently ignored — the same guarantee a CLI already gives for an unknown command. Silently dropping a flag is worse than an error: the agent gets plausible-looking output it believes is scoped/filtered and proceeds on wrong data. Covers: validate-before-dependency-call, globals always allowed, targeted migration hints for removed/renamed flags, per-subcommand flag sets for grouped nouns, and folding the --help lookup into the error so the agent self-corrects in one turn. Synced across the spec (SKILL.md), the README principle table, and the docs site. Refs kunchenguid#62 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
themightychris
force-pushed
the
docs/fail-loud-unknown-flags
branch
from
0d3e04f to
5f28580
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Closes #62.
Agents routinely invent flags. When a CLI silently ignores an unknown flag, the agent never learns it did nothing — it trusts output it believes is scoped/filtered and proceeds on wrong data. (Concrete instance: an agent nearly created a duplicate record because
list <thing> --project <slug>dropped the unsupported flag and returned an unfiltered list that looked scoped.)The SDK already fails loud on an unknown command. This codifies the same guarantee for flags as part of principle 6.
What
Adds a "Fail loud on unrecognized input" sub-principle under §6 Structured errors & exit codes:
--json,--help, …) always pass.commitment listvscommitment create).--helplookup into the error (list valid flags inline / print the concise help) so the agent fixes it in one turn rather than a guaranteed follow-up call.Synced across all three surfaces: the spec (
SKILL.md), the README principle table, and the docs site (docs/index.html).Open question (from #62)
Should the error print the command's full
--helpinline, or just the valid-flag list + a pointer? The draft recommends inlining (per §4 the follow-up call is the expensive cost; per §10 per-command help is already concise) but leaves the exact rendering to the tool. Happy to tighten the wording either way.Follow-up (not in this PR)
The implementation half #62 also asks for: have
axi-sdk-jsexport a sharedparseArgs/validateFlagsprimitive so tools get this without copy-paste (non-breaking), with central enforcement as a later breaking change. Can do that in a separate PR.