principles: add "Avoiding prompt fatigue" as §1, ahead of the security principle (PMC vote required)

[potiuk]

Summary

• Principle amendment proposal — needs a PMC vote before merge. Adds ## 1. Avoiding prompt fatigue to PRINCIPLES.md, ahead of "Privacy, security, and supply-chain integrity ship before features". Per Amending these principles, adding a principle and changing the ordering require a [VOTE] on private@ mirrored to dev@, ≥3 binding +1, no binding -1, a 72-hour window, and the result recorded on dev@ and linked from the merge commit.
• Why now: fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 found that the reference config's catch-all Bash(gh *) ask rule had been prompting on every gh read since it was written, because Claude Code evaluates ask before allow regardless of specificity. Nobody noticed for months because the prompts were being clicked through — which is RFC-AI-0002 § Layer 3a's prompt-fatigue argument playing out on the framework's own maintainers. The principle names the rule the fix relied on: read-only actions do not prompt, writes prompt once in a judgeable shape, bulk work is a bounded operation, and a prompt on a read is a defect of the same severity as a missing prompt on a write.
• Placement before the security principle is deliberate and is the part most worth debating on the vote thread: earlier principles outrank later ones, and the claim here is that a confirmation the human has learned to click through is no control at all, so keeping prompts meaningful is a precondition of the security principle, not a competitor to it.

Type of change

• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

Test plan

• prek run --files <all changed files> passes, including lychee — the renumbering touches every PRINCIPLES.md#N-… anchor in the tree (21 files) and lychee's fragment check is what proves none dangle
• Renumbering done by script (descending, boundary-anchored regex) rather than by hand: link anchors, bare PRINCIPLES.md#N, §N on lines that link the file, and the three unlinked "Principle N" mentions in the optimize-skill docs
• Token table regenerated (optimize-skill's SKILL.md changed by one digit)
• Stacked on fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 so sandbox-lint's live-vs-baseline check passes on the same working tree; rebase onto main once fix(agent-isolation): list gh write subcommands in ask instead of a catch-all that prompted on every read #1290 merges

RFC-AI-0004 compliance

• HITL — the principle strengthens the confirmation gate by keeping it readable; it does not remove any prompt on a write
• Sandbox — n/a
• Vendor neutrality — no project-specific values
• Conversational + correctable — n/a
• Write-access discipline — n/a
• Privacy LLM — n/a

Linked issues

Refs #1290 (the fix that motivated this), #1289.

Notes for reviewers (optional)

• Vote threads: a [VOTE] on private@magpie.apache.org mirrored on dev@magpie.apache.org will follow this PR; the merge commit must link the recorded result.
• If the PMC prefers the principle after the security principle, only PRINCIPLES.md and the renumbering change; the text stands either way. The ordering argument is in the Summary.
• docs/rfcs/RFC-AI-0002.md § Layer 3a gains one sentence linking the principle; no other RFC text changes beyond anchor numbers.

🤖 Generated with Claude Code

[potiuk]

Converted to draft while the Vote is runnning https://lists.apache.org/thread/bl8lhj9c0jls8h5s3172vw6gg1pvwkwb

[Kaap10]

+1 (non-binding).

I completely agree with this addition and the decision to place it as Principle 1. The UX phenomenon of 'alert fatigue' is well-documented in security engineering, and applying it as a first-class constraint for Agentic UI design is a great move. A security control that users learn to blindly click through isn't a control at all.

I love the tweaks Justin suggested. I just had one more minor thought on the phrasing here:

"a bulk operation is a bounded shape (a vetted operation with typed parameters) rather than N confirmations"

This is great, but perhaps we should explicitly add that the single confirmation for a bulk operation must present a clear summary of the batch scope? Something like: "a bulk operation is a bounded shape [...] rather than N confirmations, provided the single prompt clearly surfaces the full scope of the batch."

It ensures that when we collapse N prompts into 1, the human doesn't lose the visibility they would have had otherwise. Regardless of the phrasing tweak, this is a massive +1 from my side!

[potiuk]

This is great, but perhaps we should explicitly add that the single confirmation for a bulk operation must present a clear summary of the batch scope? Something like: "a bulk operation is a bounded shape [...] rather than N confirmations, provided the single prompt clearly surfaces the full scope of the batch."

Yeah, we could but I think no need this is how I understand what "bounded shape" means. And It always work like that (been doing that multiple times).

[Kaap10]

Makes total sense! Thanks for the clarification on the definition of "bounded shape". Looking forward to seeing this merged once the vote concludes.